Program.h revision 276479
1218885Sdim//===- llvm/Support/Program.h ------------------------------------*- C++ -*-===// 2218885Sdim// 3218885Sdim// The LLVM Compiler Infrastructure 4218885Sdim// 5218885Sdim// This file is distributed under the University of Illinois Open Source 6218885Sdim// License. See LICENSE.TXT for details. 7218885Sdim// 8218885Sdim//===----------------------------------------------------------------------===// 9218885Sdim// 10218885Sdim// This file declares the llvm::sys::Program class. 11218885Sdim// 12218885Sdim//===----------------------------------------------------------------------===// 13218885Sdim 14249423Sdim#ifndef LLVM_SUPPORT_PROGRAM_H 15249423Sdim#define LLVM_SUPPORT_PROGRAM_H 16218885Sdim 17251662Sdim#include "llvm/ADT/ArrayRef.h" 18218885Sdim#include "llvm/Support/Path.h" 19276479Sdim#include <system_error> 20218885Sdim 21218885Sdimnamespace llvm { 22218885Sdimnamespace sys { 23218885Sdim 24261991Sdim /// This is the OS-specific separator for PATH like environment variables: 25261991Sdim // a colon on Unix or a semicolon on Windows. 26261991Sdim#if defined(LLVM_ON_UNIX) 27261991Sdim const char EnvPathSeparator = ':'; 28261991Sdim#elif defined (LLVM_ON_WIN32) 29261991Sdim const char EnvPathSeparator = ';'; 30261991Sdim#endif 31218885Sdim 32261991Sdim/// @brief This struct encapsulates information about a process. 33261991Sdimstruct ProcessInfo { 34261991Sdim#if defined(LLVM_ON_UNIX) 35261991Sdim typedef pid_t ProcessId; 36261991Sdim#elif defined(LLVM_ON_WIN32) 37261991Sdim typedef unsigned long ProcessId; // Must match the type of DWORD on Windows. 38261991Sdim typedef void * HANDLE; // Must match the type of HANDLE on Windows. 39261991Sdim /// The handle to the process (available on Windows only). 40261991Sdim HANDLE ProcessHandle; 41261991Sdim#else 42261991Sdim#error "ProcessInfo is not defined for this platform!" 43261991Sdim#endif 44218885Sdim 45261991Sdim /// The process identifier. 46261991Sdim ProcessId Pid; 47218885Sdim 48261991Sdim /// The return code, set after execution. 49261991Sdim int ReturnCode; 50218885Sdim 51261991Sdim ProcessInfo(); 52261991Sdim}; 53218885Sdim 54276479Sdim /// This function attempts to locate a program in the operating 55276479Sdim /// system's file system using some pre-determined set of locations to search 56276479Sdim /// (e.g. the PATH on Unix). Paths with slashes are returned unmodified. 57276479Sdim /// 58276479Sdim /// It does not perform hashing as a shell would but instead stats each PATH 59276479Sdim /// entry individually so should generally be avoided. Core LLVM library 60276479Sdim /// functions and options should instead require fully specified paths. 61276479Sdim /// 62276479Sdim /// @returns A string containing the path of the program or an empty string if 63276479Sdim /// the program could not be found. 64261991Sdim std::string FindProgramByName(const std::string& name); 65261991Sdim 66276479Sdim // These functions change the specified standard stream (stdin or stdout) to 67276479Sdim // binary mode. They return errc::success if the specified stream 68261991Sdim // was changed. Otherwise a platform dependent error is returned. 69276479Sdim std::error_code ChangeStdinToBinary(); 70276479Sdim std::error_code ChangeStdoutToBinary(); 71261991Sdim 72261991Sdim /// This function executes the program using the arguments provided. The 73261991Sdim /// invoked program will inherit the stdin, stdout, and stderr file 74261991Sdim /// descriptors, the environment and other configuration settings of the 75261991Sdim /// invoking program. 76276479Sdim /// This function waits for the program to finish, so should be avoided in 77276479Sdim /// library functions that aren't expected to block. Consider using 78276479Sdim /// ExecuteNoWait() instead. 79261991Sdim /// @returns an integer result code indicating the status of the program. 80261991Sdim /// A zero or positive value indicates the result code of the program. 81261991Sdim /// -1 indicates failure to execute 82261991Sdim /// -2 indicates a crash during execution or timeout 83261991Sdim int ExecuteAndWait( 84261991Sdim StringRef Program, ///< Path of the program to be executed. It is 85261991Sdim /// presumed this is the result of the FindProgramByName method. 86261991Sdim const char **args, ///< A vector of strings that are passed to the 87218885Sdim ///< program. The first element should be the name of the program. 88218885Sdim ///< The list *must* be terminated by a null char* entry. 89276479Sdim const char **env = nullptr, ///< An optional vector of strings to use for 90218885Sdim ///< the program's environment. If not provided, the current program's 91218885Sdim ///< environment will be used. 92276479Sdim const StringRef **redirects = nullptr, ///< An optional array of pointers 93276479Sdim ///< to paths. If the array is null, no redirection is done. The array 94261991Sdim ///< should have a size of at least three. The inferior process's 95261991Sdim ///< stdin(0), stdout(1), and stderr(2) will be redirected to the 96261991Sdim ///< corresponding paths. 97261991Sdim ///< When an empty path is passed in, the corresponding file 98218885Sdim ///< descriptor will be disconnected (ie, /dev/null'd) in a portable 99218885Sdim ///< way. 100261991Sdim unsigned secondsToWait = 0, ///< If non-zero, this specifies the amount 101261991Sdim ///< of time to wait for the child process to exit. If the time 102261991Sdim ///< expires, the child is killed and this call returns. If zero, 103261991Sdim ///< this function will wait until the child finishes or forever if 104261991Sdim ///< it doesn't. 105218885Sdim unsigned memoryLimit = 0, ///< If non-zero, this specifies max. amount 106218885Sdim ///< of memory can be allocated by process. If memory usage will be 107218885Sdim ///< higher limit, the child is killed and this call returns. If zero 108218885Sdim ///< - no memory limit. 109276479Sdim std::string *ErrMsg = nullptr, ///< If non-zero, provides a pointer to a 110276479Sdim ///< string instance in which error messages will be returned. If the 111276479Sdim ///< string is non-empty upon return an error occurred while invoking the 112218885Sdim ///< program. 113276479Sdim bool *ExecutionFailed = nullptr); 114218885Sdim 115261991Sdim /// Similar to ExecuteAndWait, but returns immediately. 116261991Sdim /// @returns The \see ProcessInfo of the newly launced process. 117261991Sdim /// \note On Microsoft Windows systems, users will need to either call \see 118261991Sdim /// Wait until the process finished execution or win32 CloseHandle() API on 119261991Sdim /// ProcessInfo.ProcessHandle to avoid memory leaks. 120261991Sdim ProcessInfo 121276479Sdim ExecuteNoWait(StringRef Program, const char **args, const char **env = nullptr, 122276479Sdim const StringRef **redirects = nullptr, unsigned memoryLimit = 0, 123276479Sdim std::string *ErrMsg = nullptr, bool *ExecutionFailed = nullptr); 124261991Sdim 125261991Sdim /// Return true if the given arguments fit within system-specific 126261991Sdim /// argument length limits. 127261991Sdim bool argumentsFitWithinSystemLimits(ArrayRef<const char*> Args); 128261991Sdim 129261991Sdim /// This function waits for the process specified by \p PI to finish. 130261991Sdim /// \returns A \see ProcessInfo struct with Pid set to: 131261991Sdim /// \li The process id of the child process if the child process has changed 132261991Sdim /// state. 133261991Sdim /// \li 0 if the child process has not changed state. 134261991Sdim /// \note Users of this function should always check the ReturnCode member of 135261991Sdim /// the \see ProcessInfo returned from this function. 136261991Sdim ProcessInfo Wait( 137261991Sdim const ProcessInfo &PI, ///< The child process that should be waited on. 138261991Sdim unsigned SecondsToWait, ///< If non-zero, this specifies the amount of 139261991Sdim ///< time to wait for the child process to exit. If the time expires, the 140261991Sdim ///< child is killed and this function returns. If zero, this function 141261991Sdim ///< will perform a non-blocking wait on the child process. 142261991Sdim bool WaitUntilTerminates, ///< If true, ignores \p SecondsToWait and waits 143261991Sdim ///< until child has terminated. 144276479Sdim std::string *ErrMsg = nullptr ///< If non-zero, provides a pointer to a 145276479Sdim ///< string instance in which error messages will be returned. If the 146276479Sdim ///< string is non-empty upon return an error occurred while invoking the 147261991Sdim ///< program. 148218885Sdim ); 149261991Sdim } 150218885Sdim} 151218885Sdim 152218885Sdim#endif 153