[1] | 1 | /** @file
|
---|
[8245] | 2 | * IPRT - Process Management.
|
---|
[1] | 3 | */
|
---|
| 4 |
|
---|
| 5 | /*
|
---|
[98103] | 6 | * Copyright (C) 2006-2023 Oracle and/or its affiliates.
|
---|
[1] | 7 | *
|
---|
[96407] | 8 | * This file is part of VirtualBox base platform packages, as
|
---|
| 9 | * available from https://www.virtualbox.org.
|
---|
[5999] | 10 | *
|
---|
[96407] | 11 | * This program is free software; you can redistribute it and/or
|
---|
| 12 | * modify it under the terms of the GNU General Public License
|
---|
| 13 | * as published by the Free Software Foundation, in version 3 of the
|
---|
| 14 | * License.
|
---|
| 15 | *
|
---|
| 16 | * This program is distributed in the hope that it will be useful, but
|
---|
| 17 | * WITHOUT ANY WARRANTY; without even the implied warranty of
|
---|
| 18 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
---|
| 19 | * General Public License for more details.
|
---|
| 20 | *
|
---|
| 21 | * You should have received a copy of the GNU General Public License
|
---|
| 22 | * along with this program; if not, see <https://www.gnu.org/licenses>.
|
---|
| 23 | *
|
---|
[5999] | 24 | * The contents of this file may alternatively be used under the terms
|
---|
| 25 | * of the Common Development and Distribution License Version 1.0
|
---|
[96407] | 26 | * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
|
---|
| 27 | * in the VirtualBox distribution, in which case the provisions of the
|
---|
[5999] | 28 | * CDDL are applicable instead of those of the GPL.
|
---|
| 29 | *
|
---|
| 30 | * You may elect to license modified versions of this file under the
|
---|
| 31 | * terms and conditions of either the GPL or the CDDL or both.
|
---|
[96407] | 32 | *
|
---|
| 33 | * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
|
---|
[1] | 34 | */
|
---|
| 35 |
|
---|
[76557] | 36 | #ifndef IPRT_INCLUDED_process_h
|
---|
| 37 | #define IPRT_INCLUDED_process_h
|
---|
[76507] | 38 | #ifndef RT_WITHOUT_PRAGMA_ONCE
|
---|
| 39 | # pragma once
|
---|
| 40 | #endif
|
---|
[1] | 41 |
|
---|
| 42 | #include <iprt/cdefs.h>
|
---|
| 43 | #include <iprt/types.h>
|
---|
| 44 |
|
---|
[20374] | 45 | RT_C_DECLS_BEGIN
|
---|
[1] | 46 |
|
---|
| 47 | /** @defgroup grp_rt_process RTProc - Process Management
|
---|
| 48 | * @ingroup grp_rt
|
---|
| 49 | * @{
|
---|
| 50 | */
|
---|
| 51 |
|
---|
| 52 |
|
---|
| 53 | /**
|
---|
| 54 | * Process priority.
|
---|
| 55 | *
|
---|
| 56 | * The process priority is used to select how scheduling properties
|
---|
| 57 | * are assigned to the different thread types (see THREADTYPE).
|
---|
| 58 | *
|
---|
| 59 | * In addition to using the policy assigned to the process at startup (DEFAULT)
|
---|
| 60 | * it is possible to change the process priority at runtime. This allows for
|
---|
[16964] | 61 | * a GUI, resource manager or admin to adjust the general priority of a task
|
---|
[1] | 62 | * without upsetting the fine-tuned priority of the threads within.
|
---|
| 63 | */
|
---|
| 64 | typedef enum RTPROCPRIORITY
|
---|
| 65 | {
|
---|
| 66 | /** Invalid priority. */
|
---|
| 67 | RTPROCPRIORITY_INVALID = 0,
|
---|
| 68 | /** Default priority.
|
---|
[16964] | 69 | * Derive the scheduling policy from the priority of the RTR3Init()
|
---|
[1] | 70 | * and RTProcSetPriority() callers and the rights the process have
|
---|
| 71 | * to alter its own priority.
|
---|
| 72 | */
|
---|
| 73 | RTPROCPRIORITY_DEFAULT,
|
---|
| 74 | /** Flat priority.
|
---|
| 75 | * Assumes a scheduling policy which puts the process at the default priority
|
---|
| 76 | * and with all thread at the same priority.
|
---|
| 77 | */
|
---|
| 78 | RTPROCPRIORITY_FLAT,
|
---|
| 79 | /** Low priority.
|
---|
| 80 | * Assumes a scheduling policy which puts the process mostly below the
|
---|
| 81 | * default priority of the host OS.
|
---|
| 82 | */
|
---|
| 83 | RTPROCPRIORITY_LOW,
|
---|
| 84 | /** Normal priority.
|
---|
[16964] | 85 | * Assume a scheduling policy which shares the CPU resources fairly with
|
---|
[1] | 86 | * other processes running with the default priority of the host OS.
|
---|
| 87 | */
|
---|
| 88 | RTPROCPRIORITY_NORMAL,
|
---|
| 89 | /** High priority.
|
---|
| 90 | * Assumes a scheduling policy which puts the task above the default
|
---|
| 91 | * priority of the host OS. This policy might easily cause other tasks
|
---|
| 92 | * in the system to starve.
|
---|
| 93 | */
|
---|
| 94 | RTPROCPRIORITY_HIGH,
|
---|
| 95 | /** Last priority, used for validation. */
|
---|
| 96 | RTPROCPRIORITY_LAST
|
---|
| 97 | } RTPROCPRIORITY;
|
---|
| 98 |
|
---|
| 99 |
|
---|
[385] | 100 | /**
|
---|
| 101 | * Get the current process identifier.
|
---|
| 102 | *
|
---|
| 103 | * @returns Process identifier.
|
---|
| 104 | */
|
---|
| 105 | RTDECL(RTPROCESS) RTProcSelf(void);
|
---|
[1] | 106 |
|
---|
[385] | 107 |
|
---|
| 108 | #ifdef IN_RING0
|
---|
| 109 | /**
|
---|
| 110 | * Get the current process handle.
|
---|
| 111 | *
|
---|
| 112 | * @returns Ring-0 process handle.
|
---|
| 113 | */
|
---|
| 114 | RTR0DECL(RTR0PROCESS) RTR0ProcHandleSelf(void);
|
---|
| 115 | #endif
|
---|
| 116 |
|
---|
| 117 |
|
---|
[97646] | 118 | /**
|
---|
| 119 | * Translate a signal number to a short name on the form SIGXXXX.
|
---|
| 120 | *
|
---|
| 121 | * If the signal is not known, it will be formatted as a number into one of
|
---|
| 122 | * several static buffers. This means that there could be concurrency issues if
|
---|
| 123 | * this suddenly happens on multiple threads, though that is unlikely.
|
---|
| 124 | *
|
---|
| 125 | * @returns Readonly string naming the signal.
|
---|
| 126 | * @param iSignal The signal to name.
|
---|
| 127 | */
|
---|
| 128 | RTDECL(const char *) RTProcSignalName(int iSignal);
|
---|
| 129 |
|
---|
[1] | 130 | #ifdef IN_RING3
|
---|
| 131 |
|
---|
| 132 | /**
|
---|
| 133 | * Attempts to alter the priority of the current process.
|
---|
| 134 | *
|
---|
| 135 | * @returns iprt status code.
|
---|
| 136 | * @param enmPriority The new priority.
|
---|
| 137 | */
|
---|
| 138 | RTR3DECL(int) RTProcSetPriority(RTPROCPRIORITY enmPriority);
|
---|
| 139 |
|
---|
| 140 | /**
|
---|
| 141 | * Gets the current priority of this process.
|
---|
| 142 | *
|
---|
| 143 | * @returns The priority (see RTPROCPRIORITY).
|
---|
| 144 | */
|
---|
| 145 | RTR3DECL(RTPROCPRIORITY) RTProcGetPriority(void);
|
---|
| 146 |
|
---|
| 147 | /**
|
---|
| 148 | * Create a child process.
|
---|
| 149 | *
|
---|
| 150 | * @returns iprt status code.
|
---|
| 151 | * @param pszExec Executable image to use to create the child process.
|
---|
| 152 | * @param papszArgs Pointer to an array of arguments to the child. The array terminated by an entry containing NULL.
|
---|
[4475] | 153 | * @param Env Handle to the environment block for the child.
|
---|
[14999] | 154 | * @param fFlags Flags, one of the RTPROC_FLAGS_* defines.
|
---|
[1] | 155 | * @param pProcess Where to store the process identifier on successful return.
|
---|
| 156 | * The content is not changed on failure. NULL is allowed.
|
---|
| 157 | */
|
---|
[4475] | 158 | RTR3DECL(int) RTProcCreate(const char *pszExec, const char * const *papszArgs, RTENV Env, unsigned fFlags, PRTPROCESS pProcess);
|
---|
[1] | 159 |
|
---|
[26726] | 160 |
|
---|
| 161 | /**
|
---|
| 162 | * Create a child process.
|
---|
| 163 | *
|
---|
| 164 | * @returns IPRT status code.
|
---|
| 165 | *
|
---|
| 166 | * @param pszExec Executable image to use to create the child process.
|
---|
| 167 | * @param papszArgs Pointer to an array of arguments to the child. The
|
---|
| 168 | * array terminated by an entry containing NULL.
|
---|
| 169 | * @param hEnv Handle to the environment block for the child. Pass
|
---|
| 170 | * RTENV_DEFAULT to use the environment of the current
|
---|
| 171 | * process.
|
---|
| 172 | * @param fFlags Flags, one of the RTPROC_FLAGS_* defines.
|
---|
| 173 | * @param phStdIn The standard in handle to assign the new process. Pass
|
---|
[26802] | 174 | * NULL to use the same as the current process. If the
|
---|
| 175 | * handle is NIL, we'll close the standard input of the
|
---|
| 176 | * guest.
|
---|
[26726] | 177 | * @param phStdOut The standard out handle to assign the new process. Pass
|
---|
[26802] | 178 | * NULL to use the same as the current process. If the
|
---|
| 179 | * handle is NIL, we'll close the standard output of the
|
---|
| 180 | * guest.
|
---|
[26726] | 181 | * @param phStdErr The standard error handle to assign the new process. Pass
|
---|
[26802] | 182 | * NULL to use the same as the current process. If the
|
---|
| 183 | * handle is NIL, we'll close the standard error of the
|
---|
| 184 | * guest.
|
---|
[26726] | 185 | * @param pszAsUser User to run the process as. Pass NULL to use the same
|
---|
| 186 | * user as the current process.
|
---|
[59133] | 187 | * Windows: Use user\@domain (UPN, User Principal Name)
|
---|
| 188 | * format to specify a domain.
|
---|
[27676] | 189 | * @param pszPassword Password to use to authenticate @a pszAsUser. Must be
|
---|
| 190 | * NULL wif pszAsUser is NULL. Whether this is actually
|
---|
| 191 | * used or not depends on the platform.
|
---|
[80569] | 192 | * @param pvExtraData Points to additional data as per @a fFlags:
|
---|
| 193 | * - RTPROC_FLAGS_DESIRED_SESSION_ID: Pointing to a
|
---|
| 194 | * uint32_t variable with the desired session ID.
|
---|
[99109] | 195 | * - RTPROC_FLAGS_CWD: Pointing to a string constant
|
---|
| 196 | * with the directory to chdir() to under the final
|
---|
| 197 | * execution ID, before starting the process.
|
---|
| 198 | * - These flags cannot be used in the same call.
|
---|
[26726] | 199 | * @param phProcess Where to store the process handle on successful return.
|
---|
| 200 | * The content is not changed on failure. NULL is allowed.
|
---|
| 201 | *
|
---|
[27515] | 202 | * @remarks The handles does not have to be created as inheritable, but it
|
---|
| 203 | * doesn't hurt if they are as it may avoid race conditions on some
|
---|
| 204 | * platforms.
|
---|
| 205 | *
|
---|
[26726] | 206 | * @remarks The as-user feature isn't supported/implemented on all platforms and
|
---|
| 207 | * will cause a-yet-to-be-determined-error-status on these.
|
---|
| 208 | */
|
---|
| 209 | RTR3DECL(int) RTProcCreateEx(const char *pszExec, const char * const *papszArgs, RTENV hEnv, uint32_t fFlags,
|
---|
| 210 | PCRTHANDLE phStdIn, PCRTHANDLE phStdOut, PCRTHANDLE phStdErr, const char *pszAsUser,
|
---|
[80569] | 211 | const char *pszPassword, void *pvExtraData, PRTPROCESS phProcess);
|
---|
[26726] | 212 |
|
---|
| 213 | /** @name RTProcCreate and RTProcCreateEx flags
|
---|
[14999] | 214 | * @{ */
|
---|
[27743] | 215 | /** Detach the child process from the parents process tree and process group,
|
---|
| 216 | * session or/and console (depends on the platform what's done applicable).
|
---|
| 217 | *
|
---|
| 218 | * The new process will not be a direct decendent of the parent and it will not
|
---|
| 219 | * be possible to wait for it, i.e. @a phProcess shall be NULL. */
|
---|
| 220 | #define RTPROC_FLAGS_DETACHED RT_BIT(0)
|
---|
[40571] | 221 | /** Don't show the started process.
|
---|
[57753] | 222 | * This is a Windows (and maybe OS/2) concept, do not use on other platforms. */
|
---|
[34708] | 223 | #define RTPROC_FLAGS_HIDDEN RT_BIT(1)
|
---|
[40571] | 224 | /** Use special code path for starting child processes from a service (daemon).
|
---|
| 225 | * This is a windows concept for dealing with the so called "Session 0"
|
---|
| 226 | * isolation which was introduced with Windows Vista. Do not use on other
|
---|
| 227 | * platforms. */
|
---|
[29289] | 228 | #define RTPROC_FLAGS_SERVICE RT_BIT(2)
|
---|
[35558] | 229 | /** Suppress changing the process contract id for the child process
|
---|
[40571] | 230 | * on Solaris. Without this flag the contract id is always changed, as that's
|
---|
| 231 | * the more frequently used case. */
|
---|
[35558] | 232 | #define RTPROC_FLAGS_SAME_CONTRACT RT_BIT(3)
|
---|
[57753] | 233 | /** Load user profile data when executing a process.
|
---|
[92617] | 234 | * This redefines the meaning of RTENV_DEFAULT to the profile environment. See
|
---|
| 235 | * also RTPROC_FLAGS_ONLY_BASIC_PROFILE */
|
---|
[57753] | 236 | #define RTPROC_FLAGS_PROFILE RT_BIT(4)
|
---|
[40571] | 237 | /** Create process without a console window.
|
---|
| 238 | * This is a Windows (and OS/2) concept, do not use on other platforms. */
|
---|
[38618] | 239 | #define RTPROC_FLAGS_NO_WINDOW RT_BIT(5)
|
---|
[40571] | 240 | /** Search the PATH for the executable. */
|
---|
| 241 | #define RTPROC_FLAGS_SEARCH_PATH RT_BIT(6)
|
---|
[55530] | 242 | /** Don't quote and escape arguments on Windows and similar platforms where a
|
---|
| 243 | * command line is passed to the child process instead of an argument vector,
|
---|
| 244 | * just join up argv with a space between each. Ignored on platforms
|
---|
| 245 | * passing argument the vector. */
|
---|
| 246 | #define RTPROC_FLAGS_UNQUOTED_ARGS RT_BIT(7)
|
---|
[57835] | 247 | /** Consider hEnv an environment change record to be applied to RTENV_DEFAULT.
|
---|
| 248 | * If hEnv is RTENV_DEFAULT, the flag has no effect. */
|
---|
| 249 | #define RTPROC_FLAGS_ENV_CHANGE_RECORD RT_BIT(8)
|
---|
[80481] | 250 | /** Create process using the current impersonated thread token.
|
---|
| 251 | * Caller should also specify RTPROC_FLAGS_SERVICE and RTPROC_FLAGS_PROFILE.
|
---|
| 252 | * Windows only flag, ignored everywhere else. */
|
---|
| 253 | #define RTPROC_FLAGS_AS_IMPERSONATED_TOKEN RT_BIT(9)
|
---|
| 254 | /** Hint that we don't expect to ever want to wait on the process. */
|
---|
| 255 | #define RTPROC_FLAGS_NO_WAIT RT_BIT(10)
|
---|
[80569] | 256 | /** For use with RTPROC_FLAGS_SERVICE to specify a desired session ID
|
---|
| 257 | * (Windows only, ignored elsewhere). The @a pvExtraData argument points to
|
---|
[95274] | 258 | * a uint32_t containing the session ID, UINT32_MAX means any session.
|
---|
[99109] | 259 | * Cannot be set with RTPROC_FLAGS_TOKEN_SUPPLIED or RTPROC_FLAGS_CWD. */
|
---|
[80569] | 260 | #define RTPROC_FLAGS_DESIRED_SESSION_ID RT_BIT(11)
|
---|
[92617] | 261 | /** This is a modifier to RTPROC_FLAGS_PROFILE on unix systems that makes it
|
---|
| 262 | * skip trying to dump the environment of a login shell. */
|
---|
| 263 | #define RTPROC_FLAGS_ONLY_BASIC_PROFILE RT_BIT(12)
|
---|
[92671] | 264 | /** Don't translate arguments to the (guessed) child process codeset.
|
---|
| 265 | * This is ignored on Windows as it is using UTF-16. */
|
---|
| 266 | #define RTPROC_FLAGS_UTF8_ARGV RT_BIT_32(13)
|
---|
[95274] | 267 | /** Create process using supplied token. The @a pvExtraData argument points to
|
---|
| 268 | * a HANDLE containing the token used as user credentials for process creation.
|
---|
[99109] | 269 | * Cannot be set with RTPROC_FLAGS_DESIRED_SESSION_ID or RTPROC_FLAGS_CWD.
|
---|
[95274] | 270 | * Windows only flag, ignored everywhere else. */
|
---|
| 271 | #define RTPROC_FLAGS_TOKEN_SUPPLIED RT_BIT(14)
|
---|
[99109] | 272 | /** The @a pvExtraData argument points to a string containing the directory
|
---|
| 273 | * to chdir() to, under the final execution ID, before starting the process.
|
---|
| 274 | * Cannot be set with RTPROC_FLAGS_DESIRED_SESSION_ID or
|
---|
| 275 | * RTPROC_FLAGS_TOKEN_SUPPLIED. */
|
---|
| 276 | #define RTPROC_FLAGS_CWD RT_BIT(15)
|
---|
[95274] | 277 |
|
---|
[55530] | 278 | /** Valid flag mask. */
|
---|
[99109] | 279 | #define RTPROC_FLAGS_VALID_MASK UINT32_C(0xffff)
|
---|
[14999] | 280 | /** @} */
|
---|
| 281 |
|
---|
| 282 |
|
---|
[1] | 283 | /**
|
---|
| 284 | * Process exit reason.
|
---|
| 285 | */
|
---|
| 286 | typedef enum RTPROCEXITREASON
|
---|
| 287 | {
|
---|
| 288 | /** Normal exit. iStatus contains the exit code. */
|
---|
| 289 | RTPROCEXITREASON_NORMAL = 1,
|
---|
| 290 | /** Any abnormal exit. iStatus is undefined. */
|
---|
| 291 | RTPROCEXITREASON_ABEND,
|
---|
| 292 | /** Killed by a signal. The iStatus field contains the signal number. */
|
---|
| 293 | RTPROCEXITREASON_SIGNAL
|
---|
| 294 | } RTPROCEXITREASON;
|
---|
| 295 |
|
---|
| 296 | /**
|
---|
| 297 | * Process exit status.
|
---|
| 298 | */
|
---|
| 299 | typedef struct RTPROCSTATUS
|
---|
| 300 | {
|
---|
| 301 | /** The process exit status if the exit was a normal one. */
|
---|
| 302 | int iStatus;
|
---|
| 303 | /** The reason the process terminated. */
|
---|
| 304 | RTPROCEXITREASON enmReason;
|
---|
| 305 | } RTPROCSTATUS;
|
---|
| 306 | /** Pointer to a process exit status structure. */
|
---|
| 307 | typedef RTPROCSTATUS *PRTPROCSTATUS;
|
---|
| 308 | /** Pointer to a const process exit status structure. */
|
---|
| 309 | typedef const RTPROCSTATUS *PCRTPROCSTATUS;
|
---|
| 310 |
|
---|
| 311 |
|
---|
| 312 | /** Flags for RTProcWait().
|
---|
| 313 | * @{ */
|
---|
| 314 | /** Block indefinitly waiting for the process to exit. */
|
---|
| 315 | #define RTPROCWAIT_FLAGS_BLOCK 0
|
---|
[16964] | 316 | /** Don't block, just check if the process have exited. */
|
---|
[1] | 317 | #define RTPROCWAIT_FLAGS_NOBLOCK 1
|
---|
| 318 | /** @} */
|
---|
| 319 |
|
---|
| 320 | /**
|
---|
| 321 | * Waits for a process, resumes on interruption.
|
---|
| 322 | *
|
---|
[26733] | 323 | * @returns VINF_SUCCESS when the status code for the process was collected and
|
---|
| 324 | * put in *pProcStatus.
|
---|
[1] | 325 | * @returns VERR_PROCESS_NOT_FOUND if the specified process wasn't found.
|
---|
[26733] | 326 | * @returns VERR_PROCESS_RUNNING when the RTPROCWAIT_FLAGS_NOBLOCK and the
|
---|
| 327 | * process haven't exited yet.
|
---|
[1] | 328 | *
|
---|
| 329 | * @param Process The process to wait for.
|
---|
| 330 | * @param fFlags The wait flags, any of the RTPROCWAIT_FLAGS_ \#defines.
|
---|
| 331 | * @param pProcStatus Where to store the exit status on success.
|
---|
[26733] | 332 | * Optional.
|
---|
[1] | 333 | */
|
---|
| 334 | RTR3DECL(int) RTProcWait(RTPROCESS Process, unsigned fFlags, PRTPROCSTATUS pProcStatus);
|
---|
| 335 |
|
---|
| 336 | /**
|
---|
| 337 | * Waits for a process, returns on interruption.
|
---|
| 338 | *
|
---|
[26733] | 339 | * @returns VINF_SUCCESS when the status code for the process was collected and
|
---|
| 340 | * put in *pProcStatus.
|
---|
[1] | 341 | * @returns VERR_PROCESS_NOT_FOUND if the specified process wasn't found.
|
---|
[26733] | 342 | * @returns VERR_PROCESS_RUNNING when the RTPROCWAIT_FLAGS_NOBLOCK and the
|
---|
| 343 | * process haven't exited yet.
|
---|
| 344 | * @returns VERR_INTERRUPTED when the wait was interrupted by the arrival of a
|
---|
| 345 | * signal or other async event.
|
---|
[1] | 346 | *
|
---|
| 347 | * @param Process The process to wait for.
|
---|
| 348 | * @param fFlags The wait flags, any of the RTPROCWAIT_FLAGS_ \#defines.
|
---|
| 349 | * @param pProcStatus Where to store the exit status on success.
|
---|
[26733] | 350 | * Optional.
|
---|
[1] | 351 | */
|
---|
| 352 | RTR3DECL(int) RTProcWaitNoResume(RTPROCESS Process, unsigned fFlags, PRTPROCSTATUS pProcStatus);
|
---|
| 353 |
|
---|
| 354 | /**
|
---|
| 355 | * Terminates (kills) a running process.
|
---|
| 356 | *
|
---|
| 357 | * @returns IPRT status code.
|
---|
| 358 | * @param Process The process to terminate.
|
---|
| 359 | */
|
---|
| 360 | RTR3DECL(int) RTProcTerminate(RTPROCESS Process);
|
---|
| 361 |
|
---|
| 362 | /**
|
---|
| 363 | * Gets the processor affinity mask of the current process.
|
---|
| 364 | *
|
---|
| 365 | * @returns The affinity mask.
|
---|
| 366 | */
|
---|
| 367 | RTR3DECL(uint64_t) RTProcGetAffinityMask(void);
|
---|
| 368 |
|
---|
| 369 | /**
|
---|
[33806] | 370 | * Gets the short process name.
|
---|
[1] | 371 | *
|
---|
[33806] | 372 | * @returns Pointer to read-only name string.
|
---|
[83661] | 373 | * @note IPRT must've been initialized or the string will be empty.
|
---|
[33806] | 374 | */
|
---|
| 375 | RTR3DECL(const char *) RTProcShortName(void);
|
---|
| 376 |
|
---|
| 377 | /**
|
---|
| 378 | * Gets the path to the executable image of the current process.
|
---|
[1] | 379 | *
|
---|
[83661] | 380 | * @returns Pointer to read-only path string.
|
---|
| 381 | * @note IPRT must've been initialized or the string will be empty.
|
---|
| 382 | */
|
---|
| 383 | RTR3DECL(const char *) RTProcExecutablePath(void);
|
---|
| 384 |
|
---|
| 385 | /**
|
---|
| 386 | * Gets a copy of the path to the executable image of the current process.
|
---|
| 387 | *
|
---|
[33806] | 388 | * @returns pszExecPath on success. NULL on buffer overflow or other errors.
|
---|
| 389 | *
|
---|
| 390 | * @param pszExecPath Where to store the path.
|
---|
| 391 | * @param cbExecPath The size of the buffer.
|
---|
[83661] | 392 | * @note IPRT must've been initialized or the string will be empty.
|
---|
[1] | 393 | */
|
---|
[33806] | 394 | RTR3DECL(char *) RTProcGetExecutablePath(char *pszExecPath, size_t cbExecPath);
|
---|
[1] | 395 |
|
---|
[11337] | 396 | /**
|
---|
[27743] | 397 | * Daemonize the current process, making it a background process.
|
---|
| 398 | *
|
---|
| 399 | * The way this work is that it will spawn a detached / backgrounded /
|
---|
| 400 | * daemonized / call-it-what-you-want process that isn't a direct child of the
|
---|
| 401 | * current process. The spawned will have the same arguments a the caller,
|
---|
| 402 | * except that the @a pszDaemonizedOpt is appended to prevent that the new
|
---|
| 403 | * process calls this API again.
|
---|
| 404 | *
|
---|
| 405 | * The new process will have the standard handles directed to/from the
|
---|
| 406 | * bitbucket.
|
---|
| 407 | *
|
---|
| 408 | * @returns IPRT status code. On success it is normal for the caller to exit
|
---|
| 409 | * the process by returning from main().
|
---|
| 410 | *
|
---|
[57926] | 411 | * @param papszArgs The argument vector of the calling process.
|
---|
| 412 | * @param pszDaemonizedOpt The daemonized option. This is appended to the
|
---|
| 413 | * end of the parameter list of the daemonized process.
|
---|
[27743] | 414 | */
|
---|
| 415 | RTR3DECL(int) RTProcDaemonize(const char * const *papszArgs, const char *pszDaemonizedOpt);
|
---|
| 416 |
|
---|
| 417 | /**
|
---|
[11337] | 418 | * Daemonize the current process, making it a background process. The current
|
---|
| 419 | * process will exit if daemonizing is successful.
|
---|
| 420 | *
|
---|
[27743] | 421 | * @returns IPRT status code. On success it will only return in the child
|
---|
| 422 | * process, the parent will exit. On failure, it will return in the
|
---|
| 423 | * parent process and no child has been spawned.
|
---|
| 424 | *
|
---|
[11337] | 425 | * @param fNoChDir Pass false to change working directory to "/".
|
---|
| 426 | * @param fNoClose Pass false to redirect standard file streams to the null device.
|
---|
| 427 | * @param pszPidfile Path to a file to write the process id of the daemon
|
---|
| 428 | * process to. Daemonizing will fail if this file already
|
---|
| 429 | * exists or cannot be written. May be NULL.
|
---|
| 430 | */
|
---|
[27743] | 431 | RTR3DECL(int) RTProcDaemonizeUsingFork(bool fNoChDir, bool fNoClose, const char *pszPidfile);
|
---|
[11337] | 432 |
|
---|
[16999] | 433 | /**
|
---|
[17018] | 434 | * Check if the given process is running on the system.
|
---|
[16999] | 435 | *
|
---|
[17018] | 436 | * This check is case sensitive on most systems, except for Windows, OS/2 and
|
---|
| 437 | * Darwin.
|
---|
| 438 | *
|
---|
[16999] | 439 | * @returns true if the process is running & false otherwise.
|
---|
[17018] | 440 | * @param pszName Process name to search for. If no path is given only the
|
---|
| 441 | * filename part of the running process set will be
|
---|
| 442 | * matched. If a path is specified, the full path will be
|
---|
| 443 | * matched.
|
---|
[16999] | 444 | */
|
---|
| 445 | RTR3DECL(bool) RTProcIsRunningByName(const char *pszName);
|
---|
| 446 |
|
---|
[41919] | 447 | /**
|
---|
[51770] | 448 | * Queries the parent process ID.
|
---|
| 449 | *
|
---|
| 450 | * @returns IPRT status code
|
---|
| 451 | * @param hProcess The process to query the parent of.
|
---|
| 452 | * @param phParent Where to return the parent process ID.
|
---|
| 453 | */
|
---|
| 454 | RTR3DECL(int) RTProcQueryParent(RTPROCESS hProcess, PRTPROCESS phParent);
|
---|
| 455 |
|
---|
| 456 | /**
|
---|
[41919] | 457 | * Query the username of the given process.
|
---|
| 458 | *
|
---|
| 459 | * @returns IPRT status code.
|
---|
| 460 | * @retval VERR_BUFFER_OVERFLOW if the given buffer size is to small for the username.
|
---|
| 461 | * @param hProcess The process handle to query the username for.
|
---|
[57916] | 462 | * NIL_PROCESS is an alias for the current process.
|
---|
[41919] | 463 | * @param pszUser Where to store the user name on success.
|
---|
| 464 | * @param cbUser The size of the user name buffer.
|
---|
| 465 | * @param pcbUser Where to store the username length on success
|
---|
| 466 | * or the required buffer size if VERR_BUFFER_OVERFLOW
|
---|
| 467 | * is returned.
|
---|
| 468 | */
|
---|
[57916] | 469 | RTR3DECL(int) RTProcQueryUsername(RTPROCESS hProcess, char *pszUser, size_t cbUser, size_t *pcbUser);
|
---|
[41919] | 470 |
|
---|
[42067] | 471 | /**
|
---|
| 472 | * Query the username of the given process allocating the string for the username.
|
---|
| 473 | *
|
---|
| 474 | * @returns IPRT status code.
|
---|
| 475 | * @param hProcess The process handle to query the username for.
|
---|
| 476 | * @param ppszUser Where to store the pointer to the string containing
|
---|
| 477 | * the username on success. Free with RTStrFree().
|
---|
| 478 | */
|
---|
| 479 | RTR3DECL(int) RTProcQueryUsernameA(RTPROCESS hProcess, char **ppszUser);
|
---|
| 480 |
|
---|
[385] | 481 | #endif /* IN_RING3 */
|
---|
[1] | 482 |
|
---|
| 483 | /** @} */
|
---|
| 484 |
|
---|
[20374] | 485 | RT_C_DECLS_END
|
---|
[1] | 486 |
|
---|
[76585] | 487 | #endif /* !IPRT_INCLUDED_process_h */
|
---|
[1] | 488 |
|
---|