LLVM API Documentation

Program.h

Go to the documentation of this file.
00001 //===- llvm/System/Program.h ------------------------------------*- C++ -*-===//
00002 //
00003 //                     The LLVM Compiler Infrastructure
00004 //
00005 // This file is distributed under the University of Illinois Open Source
00006 // License. See LICENSE.TXT for details.
00007 //
00008 //===----------------------------------------------------------------------===//
00009 //
00010 // This file declares the llvm::sys::Program class.
00011 //
00012 //===----------------------------------------------------------------------===//
00013 
00014 #ifndef LLVM_SYSTEM_PROGRAM_H
00015 #define LLVM_SYSTEM_PROGRAM_H
00016 
00017 #include "llvm/System/Path.h"
00018 
00019 namespace llvm {
00020 namespace sys {
00021 
00022   // TODO: Add operations to communicate with the process, redirect its I/O,
00023   // etc.
00024 
00025   /// This class provides an abstraction for programs that are executable by the
00026   /// operating system. It provides a platform generic way to find executable
00027   /// programs from the path and to execute them in various ways. The sys::Path
00028   /// class is used to specify the location of the Program.
00029   /// @since 1.4
00030   /// @brief An abstraction for finding and executing programs.
00031   class Program {
00032     /// Opaque handle for target specific data.
00033   void *Data;
00034 
00035     unsigned Pid_;
00036 
00037     // Noncopyable.
00038     Program(const Program& other);
00039     Program& operator=(const Program& other);
00040 
00041     /// @name Methods
00042     /// @{
00043   public:
00044 
00045     Program();
00046   ~Program();
00047   
00048     /// Return process ID of this program.
00049     unsigned GetPid() { return Pid_; }
00050 
00051     /// This function executes the program using the \p arguments provided.  The
00052     /// invoked program will inherit the stdin, stdout, and stderr file
00053     /// descriptors, the environment and other configuration settings of the
00054     /// invoking program. If Path::executable() does not return true when this
00055     /// function is called then a std::string is thrown.
00056     /// @returns false in case of error, true otherwise.
00057     /// @see FindProgramByName
00058     /// @brief Executes the program with the given set of \p args.
00059     bool Execute
00060     ( const Path& path,  ///< sys::Path object providing the path of the
00061       ///< program to be executed. It is presumed this is the result of
00062       ///< the FindProgramByName method.
00063       const char** args, ///< A vector of strings that are passed to the
00064       ///< program.  The first element should be the name of the program.
00065       ///< The list *must* be terminated by a null char* entry.
00066       const char ** env = 0, ///< An optional vector of strings to use for
00067       ///< the program's environment. If not provided, the current program's
00068       ///< environment will be used.
00069       const sys::Path** redirects = 0, ///< An optional array of pointers to
00070       ///< Paths. If the array is null, no redirection is done. The array
00071       ///< should have a size of at least three. If the pointer in the array
00072       ///< are not null, then the inferior process's stdin(0), stdout(1),
00073       ///< and stderr(2) will be redirected to the corresponding Paths.
00074       ///< When an empty Path is passed in, the corresponding file
00075       ///< descriptor will be disconnected (ie, /dev/null'd) in a portable
00076       ///< way.
00077       unsigned memoryLimit = 0, ///< If non-zero, this specifies max. amount
00078       ///< of memory can be allocated by process. If memory usage will be
00079       ///< higher limit, the child is killed and this call returns. If zero
00080       ///< - no memory limit.
00081       std::string* ErrMsg = 0 ///< If non-zero, provides a pointer to a string
00082       ///< instance in which error messages will be returned. If the string
00083       ///< is non-empty upon return an error occurred while invoking the
00084       ///< program.
00085       );
00086 
00087     /// This function waits for the program to exit. This function will block
00088     /// the current program until the invoked program exits.
00089     /// @returns an integer result code indicating the status of the program.
00090     /// A zero or positive value indicates the result code of the program. A
00091     /// negative value is the signal number on which it terminated.
00092     /// @see Execute
00093     /// @brief Waits for the program to exit.
00094     int Wait
00095     ( unsigned secondsToWait = 0, ///< If non-zero, this specifies the amount
00096       ///< of time to wait for the child process to exit. If the time
00097       ///< expires, the child is killed and this call returns. If zero,
00098       ///< this function will wait until the child finishes or forever if
00099       ///< it doesn't.
00100       std::string* ErrMsg = 0 ///< If non-zero, provides a pointer to a string
00101       ///< instance in which error messages will be returned. If the string
00102       ///< is non-empty upon return an error occurred while invoking the
00103       ///< program.
00104       );
00105 
00106     /// This static constructor (factory) will attempt to locate a program in
00107     /// the operating system's file system using some pre-determined set of
00108     /// locations to search (e.g. the PATH on Unix).
00109     /// @returns A Path object initialized to the path of the program or a
00110     /// Path object that is empty (invalid) if the program could not be found.
00111     /// @throws nothing
00112     /// @brief Construct a Program by finding it by name.
00113     static Path FindProgramByName(const std::string& name);
00114 
00115     // These methods change the specified standard stream (stdin or stdout) to
00116     // binary mode. They return true if an error occurred
00117     static bool ChangeStdinToBinary();
00118     static bool ChangeStdoutToBinary();
00119 
00120     /// A convenience function equivalent to Program prg; prg.Execute(..);
00121     /// prg.Wait(..);
00122     /// @throws nothing
00123     /// @see Execute, Wait
00124     static int ExecuteAndWait(const Path& path,
00125                               const char** args,
00126                               const char ** env = 0,
00127                               const sys::Path** redirects = 0,
00128                               unsigned secondsToWait = 0,
00129                               unsigned memoryLimit = 0,
00130                               std::string* ErrMsg = 0);
00131 
00132     /// A convenience function equivalent to Program prg; prg.Execute(..);
00133     /// @throws nothing
00134     /// @see Execute
00135     static void ExecuteNoWait(const Path& path,
00136                               const char** args,
00137                               const char ** env = 0,
00138                               const sys::Path** redirects = 0,
00139                               unsigned memoryLimit = 0,
00140                               std::string* ErrMsg = 0);
00141 
00142     /// @}
00143 
00144   };
00145 }
00146 }
00147 
00148 #endif