LLVM API Documentation
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