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