1 //===- llvm/Support/Process.h -----------------------------------*- C++ -*-===// 2 // 3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4 // See https://llvm.org/LICENSE.txt for license information. 5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6 // 7 //===----------------------------------------------------------------------===// 8 /// \file 9 /// 10 /// Provides a library for accessing information about this process and other 11 /// processes on the operating system. Also provides means of spawning 12 /// subprocess for commands. The design of this library is modeled after the 13 /// proposed design of the Boost.Process library, and is design specifically to 14 /// follow the style of standard libraries and potentially become a proposal 15 /// for a standard library. 16 /// 17 /// This file declares the llvm::sys::Process class which contains a collection 18 /// of legacy static interfaces for extracting various information about the 19 /// current process. The goal is to migrate users of this API over to the new 20 /// interfaces. 21 /// 22 //===----------------------------------------------------------------------===// 23 24 #ifndef LLVM_SUPPORT_PROCESS_H 25 #define LLVM_SUPPORT_PROCESS_H 26 27 #include "llvm/ADT/Optional.h" 28 #include "llvm/Support/Allocator.h" 29 #include "llvm/Support/Chrono.h" 30 #include "llvm/Support/DataTypes.h" 31 #include "llvm/Support/Error.h" 32 #include <system_error> 33 34 namespace llvm { 35 template <typename T> class ArrayRef; 36 class StringRef; 37 38 namespace sys { 39 40 41 /// A collection of legacy interfaces for querying information about the 42 /// current executing process. 43 class Process { 44 public: 45 /// Get the process's page size. 46 /// This may fail if the underlying syscall returns an error. In most cases, 47 /// page size information is used for optimization, and this error can be 48 /// safely discarded by calling consumeError, and an estimated page size 49 /// substituted instead. 50 static Expected<unsigned> getPageSize(); 51 52 /// Get the process's estimated page size. 53 /// This function always succeeds, but if the underlying syscall to determine 54 /// the page size fails then this will silently return an estimated page size. 55 /// The estimated page size is guaranteed to be a power of 2. 56 static unsigned getPageSizeEstimate() { 57 if (auto PageSize = getPageSize()) 58 return *PageSize; 59 else { 60 consumeError(PageSize.takeError()); 61 return 4096; 62 } 63 } 64 65 /// Return process memory usage. 66 /// This static function will return the total amount of memory allocated 67 /// by the process. This only counts the memory allocated via the malloc, 68 /// calloc and realloc functions and includes any "free" holes in the 69 /// allocated space. 70 static size_t GetMallocUsage(); 71 72 /// This static function will set \p user_time to the amount of CPU time 73 /// spent in user (non-kernel) mode and \p sys_time to the amount of CPU 74 /// time spent in system (kernel) mode. If the operating system does not 75 /// support collection of these metrics, a zero duration will be for both 76 /// values. 77 /// \param elapsed Returns the system_clock::now() giving current time 78 /// \param user_time Returns the current amount of user time for the process 79 /// \param sys_time Returns the current amount of system time for the process 80 static void GetTimeUsage(TimePoint<> &elapsed, 81 std::chrono::nanoseconds &user_time, 82 std::chrono::nanoseconds &sys_time); 83 84 /// This function makes the necessary calls to the operating system to 85 /// prevent core files or any other kind of large memory dumps that can 86 /// occur when a program fails. 87 /// Prevent core file generation. 88 static void PreventCoreFiles(); 89 90 /// true if PreventCoreFiles has been called, false otherwise. 91 static bool AreCoreFilesPrevented(); 92 93 // This function returns the environment variable \arg name's value as a UTF-8 94 // string. \arg Name is assumed to be in UTF-8 encoding too. 95 static Optional<std::string> GetEnv(StringRef name); 96 97 /// This function searches for an existing file in the list of directories 98 /// in a PATH like environment variable, and returns the first file found, 99 /// according to the order of the entries in the PATH like environment 100 /// variable. If an ignore list is specified, then any folder which is in 101 /// the PATH like environment variable but is also in IgnoreList is not 102 /// considered. 103 static Optional<std::string> FindInEnvPath(StringRef EnvName, 104 StringRef FileName, 105 ArrayRef<std::string> IgnoreList); 106 107 static Optional<std::string> FindInEnvPath(StringRef EnvName, 108 StringRef FileName); 109 110 // This functions ensures that the standard file descriptors (input, output, 111 // and error) are properly mapped to a file descriptor before we use any of 112 // them. This should only be called by standalone programs, library 113 // components should not call this. 114 static std::error_code FixupStandardFileDescriptors(); 115 116 // This function safely closes a file descriptor. It is not safe to retry 117 // close(2) when it returns with errno equivalent to EINTR; this is because 118 // *nixen cannot agree if the file descriptor is, in fact, closed when this 119 // occurs. 120 // 121 // N.B. Some operating systems, due to thread cancellation, cannot properly 122 // guarantee that it will or will not be closed one way or the other! 123 static std::error_code SafelyCloseFileDescriptor(int FD); 124 125 /// This function determines if the standard input is connected directly 126 /// to a user's input (keyboard probably), rather than coming from a file 127 /// or pipe. 128 static bool StandardInIsUserInput(); 129 130 /// This function determines if the standard output is connected to a 131 /// "tty" or "console" window. That is, the output would be displayed to 132 /// the user rather than being put on a pipe or stored in a file. 133 static bool StandardOutIsDisplayed(); 134 135 /// This function determines if the standard error is connected to a 136 /// "tty" or "console" window. That is, the output would be displayed to 137 /// the user rather than being put on a pipe or stored in a file. 138 static bool StandardErrIsDisplayed(); 139 140 /// This function determines if the given file descriptor is connected to 141 /// a "tty" or "console" window. That is, the output would be displayed to 142 /// the user rather than being put on a pipe or stored in a file. 143 static bool FileDescriptorIsDisplayed(int fd); 144 145 /// This function determines if the given file descriptor is displayd and 146 /// supports colors. 147 static bool FileDescriptorHasColors(int fd); 148 149 /// This function determines the number of columns in the window 150 /// if standard output is connected to a "tty" or "console" 151 /// window. If standard output is not connected to a tty or 152 /// console, or if the number of columns cannot be determined, 153 /// this routine returns zero. 154 static unsigned StandardOutColumns(); 155 156 /// This function determines the number of columns in the window 157 /// if standard error is connected to a "tty" or "console" 158 /// window. If standard error is not connected to a tty or 159 /// console, or if the number of columns cannot be determined, 160 /// this routine returns zero. 161 static unsigned StandardErrColumns(); 162 163 /// This function determines whether the terminal connected to standard 164 /// output supports colors. If standard output is not connected to a 165 /// terminal, this function returns false. 166 static bool StandardOutHasColors(); 167 168 /// This function determines whether the terminal connected to standard 169 /// error supports colors. If standard error is not connected to a 170 /// terminal, this function returns false. 171 static bool StandardErrHasColors(); 172 173 /// Enables or disables whether ANSI escape sequences are used to output 174 /// colors. This only has an effect on Windows. 175 /// Note: Setting this option is not thread-safe and should only be done 176 /// during initialization. 177 static void UseANSIEscapeCodes(bool enable); 178 179 /// Whether changing colors requires the output to be flushed. 180 /// This is needed on systems that don't support escape sequences for 181 /// changing colors. 182 static bool ColorNeedsFlush(); 183 184 /// This function returns the colorcode escape sequences. 185 /// If ColorNeedsFlush() is true then this function will change the colors 186 /// and return an empty escape sequence. In that case it is the 187 /// responsibility of the client to flush the output stream prior to 188 /// calling this function. 189 static const char *OutputColor(char c, bool bold, bool bg); 190 191 /// Same as OutputColor, but only enables the bold attribute. 192 static const char *OutputBold(bool bg); 193 194 /// This function returns the escape sequence to reverse forground and 195 /// background colors. 196 static const char *OutputReverse(); 197 198 /// Resets the terminals colors, or returns an escape sequence to do so. 199 static const char *ResetColor(); 200 201 /// Get the result of a process wide random number generator. The 202 /// generator will be automatically seeded in non-deterministic fashion. 203 static unsigned GetRandomNumber(); 204 205 /// Equivalent to ::exit(), except when running inside a CrashRecoveryContext. 206 /// In that case, the control flow will resume after RunSafely(), like for a 207 /// crash, rather than exiting the current process. 208 LLVM_ATTRIBUTE_NORETURN 209 static void Exit(int RetCode); 210 }; 211 212 } 213 } 214 215 #endif 216