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/AllocatorBase.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 using Pid = int32_t; 46 47 /// Get the process's identifier. 48 static Pid getProcessId(); 49 50 /// Get the process's page size. 51 /// This may fail if the underlying syscall returns an error. In most cases, 52 /// page size information is used for optimization, and this error can be 53 /// safely discarded by calling consumeError, and an estimated page size 54 /// substituted instead. 55 static Expected<unsigned> getPageSize(); 56 57 /// Get the process's estimated page size. 58 /// This function always succeeds, but if the underlying syscall to determine 59 /// the page size fails then this will silently return an estimated page size. 60 /// The estimated page size is guaranteed to be a power of 2. 61 static unsigned getPageSizeEstimate() { 62 if (auto PageSize = getPageSize()) 63 return *PageSize; 64 else { 65 consumeError(PageSize.takeError()); 66 return 4096; 67 } 68 } 69 70 /// Return process memory usage. 71 /// This static function will return the total amount of memory allocated 72 /// by the process. This only counts the memory allocated via the malloc, 73 /// calloc and realloc functions and includes any "free" holes in the 74 /// allocated space. 75 static size_t GetMallocUsage(); 76 77 /// This static function will set \p user_time to the amount of CPU time 78 /// spent in user (non-kernel) mode and \p sys_time to the amount of CPU 79 /// time spent in system (kernel) mode. If the operating system does not 80 /// support collection of these metrics, a zero duration will be for both 81 /// values. 82 /// \param elapsed Returns the system_clock::now() giving current time 83 /// \param user_time Returns the current amount of user time for the process 84 /// \param sys_time Returns the current amount of system time for the process 85 static void GetTimeUsage(TimePoint<> &elapsed, 86 std::chrono::nanoseconds &user_time, 87 std::chrono::nanoseconds &sys_time); 88 89 /// This function makes the necessary calls to the operating system to 90 /// prevent core files or any other kind of large memory dumps that can 91 /// occur when a program fails. 92 /// Prevent core file generation. 93 static void PreventCoreFiles(); 94 95 /// true if PreventCoreFiles has been called, false otherwise. 96 static bool AreCoreFilesPrevented(); 97 98 // This function returns the environment variable \arg name's value as a UTF-8 99 // string. \arg Name is assumed to be in UTF-8 encoding too. 100 static Optional<std::string> GetEnv(StringRef name); 101 102 /// This function searches for an existing file in the list of directories 103 /// in a PATH like environment variable, and returns the first file found, 104 /// according to the order of the entries in the PATH like environment 105 /// variable. If an ignore list is specified, then any folder which is in 106 /// the PATH like environment variable but is also in IgnoreList is not 107 /// considered. 108 static Optional<std::string> FindInEnvPath(StringRef EnvName, 109 StringRef FileName, 110 ArrayRef<std::string> IgnoreList); 111 112 static Optional<std::string> FindInEnvPath(StringRef EnvName, 113 StringRef FileName); 114 115 // This functions ensures that the standard file descriptors (input, output, 116 // and error) are properly mapped to a file descriptor before we use any of 117 // them. This should only be called by standalone programs, library 118 // components should not call this. 119 static std::error_code FixupStandardFileDescriptors(); 120 121 // This function safely closes a file descriptor. It is not safe to retry 122 // close(2) when it returns with errno equivalent to EINTR; this is because 123 // *nixen cannot agree if the file descriptor is, in fact, closed when this 124 // occurs. 125 // 126 // N.B. Some operating systems, due to thread cancellation, cannot properly 127 // guarantee that it will or will not be closed one way or the other! 128 static std::error_code SafelyCloseFileDescriptor(int FD); 129 130 /// This function determines if the standard input is connected directly 131 /// to a user's input (keyboard probably), rather than coming from a file 132 /// or pipe. 133 static bool StandardInIsUserInput(); 134 135 /// This function determines if the standard output 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 StandardOutIsDisplayed(); 139 140 /// This function determines if the standard error is connected to a 141 /// "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 StandardErrIsDisplayed(); 144 145 /// This function determines if the given file descriptor is connected to 146 /// a "tty" or "console" window. That is, the output would be displayed to 147 /// the user rather than being put on a pipe or stored in a file. 148 static bool FileDescriptorIsDisplayed(int fd); 149 150 /// This function determines if the given file descriptor is displayd and 151 /// supports colors. 152 static bool FileDescriptorHasColors(int fd); 153 154 /// This function determines the number of columns in the window 155 /// if standard output is connected to a "tty" or "console" 156 /// window. If standard output is not connected to a tty or 157 /// console, or if the number of columns cannot be determined, 158 /// this routine returns zero. 159 static unsigned StandardOutColumns(); 160 161 /// This function determines the number of columns in the window 162 /// if standard error is connected to a "tty" or "console" 163 /// window. If standard error is not connected to a tty or 164 /// console, or if the number of columns cannot be determined, 165 /// this routine returns zero. 166 static unsigned StandardErrColumns(); 167 168 /// This function determines whether the terminal connected to standard 169 /// output supports colors. If standard output is not connected to a 170 /// terminal, this function returns false. 171 static bool StandardOutHasColors(); 172 173 /// This function determines whether the terminal connected to standard 174 /// error supports colors. If standard error is not connected to a 175 /// terminal, this function returns false. 176 static bool StandardErrHasColors(); 177 178 /// Enables or disables whether ANSI escape sequences are used to output 179 /// colors. This only has an effect on Windows. 180 /// Note: Setting this option is not thread-safe and should only be done 181 /// during initialization. 182 static void UseANSIEscapeCodes(bool enable); 183 184 /// Whether changing colors requires the output to be flushed. 185 /// This is needed on systems that don't support escape sequences for 186 /// changing colors. 187 static bool ColorNeedsFlush(); 188 189 /// This function returns the colorcode escape sequences. 190 /// If ColorNeedsFlush() is true then this function will change the colors 191 /// and return an empty escape sequence. In that case it is the 192 /// responsibility of the client to flush the output stream prior to 193 /// calling this function. 194 static const char *OutputColor(char c, bool bold, bool bg); 195 196 /// Same as OutputColor, but only enables the bold attribute. 197 static const char *OutputBold(bool bg); 198 199 /// This function returns the escape sequence to reverse forground and 200 /// background colors. 201 static const char *OutputReverse(); 202 203 /// Resets the terminals colors, or returns an escape sequence to do so. 204 static const char *ResetColor(); 205 206 /// Get the result of a process wide random number generator. The 207 /// generator will be automatically seeded in non-deterministic fashion. 208 static unsigned GetRandomNumber(); 209 210 /// Equivalent to ::exit(), except when running inside a CrashRecoveryContext. 211 /// In that case, the control flow will resume after RunSafely(), like for a 212 /// crash, rather than exiting the current process. 213 LLVM_ATTRIBUTE_NORETURN 214 static void Exit(int RetCode); 215 }; 216 217 } 218 } 219 220 #endif 221