1 //===- llvm/Support/Program.h ------------------------------------*- C++ -*-===// 2 // 3 // The LLVM Compiler Infrastructure 4 // 5 // This file is distributed under the University of Illinois Open Source 6 // License. See LICENSE.TXT for details. 7 // 8 //===----------------------------------------------------------------------===// 9 // 10 // This file declares the llvm::sys::Program class. 11 // 12 //===----------------------------------------------------------------------===// 13 14 #ifndef LLVM_SYSTEM_PROGRAM_H 15 #define LLVM_SYSTEM_PROGRAM_H 16 17 #include "llvm/Support/Path.h" 18 19 namespace llvm { 20 namespace sys { 21 22 // TODO: Add operations to communicate with the process, redirect its I/O, 23 // etc. 24 25 /// This class provides an abstraction for programs that are executable by the 26 /// operating system. It provides a platform generic way to find executable 27 /// programs from the path and to execute them in various ways. The sys::Path 28 /// class is used to specify the location of the Program. 29 /// @since 1.4 30 /// @brief An abstraction for finding and executing programs. 31 class Program { 32 /// Opaque handle for target specific data. 33 void *Data_; 34 35 // Noncopyable. 36 Program(const Program& other); 37 Program& operator=(const Program& other); 38 39 /// @name Methods 40 /// @{ 41 public: 42 43 Program(); 44 ~Program(); 45 46 /// Return process ID of this program. 47 unsigned GetPid() const; 48 49 /// This function executes the program using the \p arguments provided. The 50 /// invoked program will inherit the stdin, stdout, and stderr file 51 /// descriptors, the environment and other configuration settings of the 52 /// invoking program. If Path::executable() does not return true when this 53 /// function is called then a std::string is thrown. 54 /// @returns false in case of error, true otherwise. 55 /// @see FindProgramByName 56 /// @brief Executes the program with the given set of \p args. 57 bool Execute 58 ( const Path& path, ///< sys::Path object providing the path of the 59 ///< program to be executed. It is presumed this is the result of 60 ///< the FindProgramByName method. 61 const char** args, ///< A vector of strings that are passed to the 62 ///< program. The first element should be the name of the program. 63 ///< The list *must* be terminated by a null char* entry. 64 const char ** env = 0, ///< An optional vector of strings to use for 65 ///< the program's environment. If not provided, the current program's 66 ///< environment will be used. 67 const sys::Path** redirects = 0, ///< An optional array of pointers to 68 ///< Paths. If the array is null, no redirection is done. The array 69 ///< should have a size of at least three. If the pointer in the array 70 ///< are not null, then the inferior process's stdin(0), stdout(1), 71 ///< and stderr(2) will be redirected to the corresponding Paths. 72 ///< When an empty Path is passed in, the corresponding file 73 ///< descriptor will be disconnected (ie, /dev/null'd) in a portable 74 ///< way. 75 unsigned memoryLimit = 0, ///< If non-zero, this specifies max. amount 76 ///< of memory can be allocated by process. If memory usage will be 77 ///< higher limit, the child is killed and this call returns. If zero 78 ///< - no memory limit. 79 std::string* ErrMsg = 0 ///< If non-zero, provides a pointer to a string 80 ///< instance in which error messages will be returned. If the string 81 ///< is non-empty upon return an error occurred while invoking the 82 ///< program. 83 ); 84 85 /// This function waits for the program to exit. This function will block 86 /// the current program until the invoked program exits. 87 /// @returns an integer result code indicating the status of the program. 88 /// A zero or positive value indicates the result code of the program. 89 /// -1 indicates failure to execute 90 /// -2 indicates a crash during execution or timeout 91 /// @see Execute 92 /// @brief Waits for the program to exit. 93 int Wait 94 ( const Path& path, ///< The path to the child process executable. 95 unsigned secondsToWait, ///< If non-zero, this specifies the amount 96 ///< of time to wait for the child process to exit. If the time 97 ///< expires, the child is killed and this call returns. If zero, 98 ///< this function will wait until the child finishes or forever if 99 ///< it doesn't. 100 std::string* ErrMsg ///< If non-zero, provides a pointer to a string 101 ///< instance in which error messages will be returned. If the string 102 ///< is non-empty upon return an error occurred while waiting. 103 ); 104 105 /// This function terminates the program. 106 /// @returns true if an error occurred. 107 /// @see Execute 108 /// @brief Terminates the program. 109 bool Kill 110 ( std::string* ErrMsg = 0 ///< If non-zero, provides a pointer to a string 111 ///< instance in which error messages will be returned. If the string 112 ///< is non-empty upon return an error occurred while killing the 113 ///< program. 114 ); 115 116 /// This static constructor (factory) will attempt to locate a program in 117 /// the operating system's file system using some pre-determined set of 118 /// locations to search (e.g. the PATH on Unix). Paths with slashes are 119 /// returned unmodified. 120 /// @returns A Path object initialized to the path of the program or a 121 /// Path object that is empty (invalid) if the program could not be found. 122 /// @brief Construct a Program by finding it by name. 123 static Path FindProgramByName(const std::string& name); 124 125 // These methods change the specified standard stream (stdin, 126 // stdout, or stderr) to binary mode. They return true if an error 127 // occurred 128 static bool ChangeStdinToBinary(); 129 static bool ChangeStdoutToBinary(); 130 static bool ChangeStderrToBinary(); 131 132 /// A convenience function equivalent to Program prg; prg.Execute(..); 133 /// prg.Wait(..); 134 /// @see Execute, Wait 135 static int ExecuteAndWait(const Path& path, 136 const char** args, 137 const char ** env = 0, 138 const sys::Path** redirects = 0, 139 unsigned secondsToWait = 0, 140 unsigned memoryLimit = 0, 141 std::string* ErrMsg = 0); 142 143 /// A convenience function equivalent to Program prg; prg.Execute(..); 144 /// @see Execute 145 static void ExecuteNoWait(const Path& path, 146 const char** args, 147 const char ** env = 0, 148 const sys::Path** redirects = 0, 149 unsigned memoryLimit = 0, 150 std::string* ErrMsg = 0); 151 152 /// @} 153 154 }; 155 } 156 } 157 158 #endif 159
