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