VirtualBox

source: vbox/trunk/include/iprt/process.h@ 103224

Last change on this file since 103224 was 99109, checked in by vboxsync, 19 months ago

IPRT/process: Added RTPROC_FLAGS_CWD to RTProcCreateEx(), to be able to set the current working directory for created processes. bugref:8053

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 19.4 KB
Line 
1/** @file
2 * IPRT - Process Management.
3 */
4
5/*
6 * Copyright (C) 2006-2023 Oracle and/or its affiliates.
7 *
8 * This file is part of VirtualBox base platform packages, as
9 * available from https://www.virtualbox.org.
10 *
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 *
24 * The contents of this file may alternatively be used under the terms
25 * of the Common Development and Distribution License Version 1.0
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
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.
32 *
33 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
34 */
35
36#ifndef IPRT_INCLUDED_process_h
37#define IPRT_INCLUDED_process_h
38#ifndef RT_WITHOUT_PRAGMA_ONCE
39# pragma once
40#endif
41
42#include <iprt/cdefs.h>
43#include <iprt/types.h>
44
45RT_C_DECLS_BEGIN
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
61 * a GUI, resource manager or admin to adjust the general priority of a task
62 * without upsetting the fine-tuned priority of the threads within.
63 */
64typedef enum RTPROCPRIORITY
65{
66 /** Invalid priority. */
67 RTPROCPRIORITY_INVALID = 0,
68 /** Default priority.
69 * Derive the scheduling policy from the priority of the RTR3Init()
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.
85 * Assume a scheduling policy which shares the CPU resources fairly with
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
100/**
101 * Get the current process identifier.
102 *
103 * @returns Process identifier.
104 */
105RTDECL(RTPROCESS) RTProcSelf(void);
106
107
108#ifdef IN_RING0
109/**
110 * Get the current process handle.
111 *
112 * @returns Ring-0 process handle.
113 */
114RTR0DECL(RTR0PROCESS) RTR0ProcHandleSelf(void);
115#endif
116
117
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 */
128RTDECL(const char *) RTProcSignalName(int iSignal);
129
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 */
138RTR3DECL(int) RTProcSetPriority(RTPROCPRIORITY enmPriority);
139
140/**
141 * Gets the current priority of this process.
142 *
143 * @returns The priority (see RTPROCPRIORITY).
144 */
145RTR3DECL(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.
153 * @param Env Handle to the environment block for the child.
154 * @param fFlags Flags, one of the RTPROC_FLAGS_* defines.
155 * @param pProcess Where to store the process identifier on successful return.
156 * The content is not changed on failure. NULL is allowed.
157 */
158RTR3DECL(int) RTProcCreate(const char *pszExec, const char * const *papszArgs, RTENV Env, unsigned fFlags, PRTPROCESS pProcess);
159
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
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.
177 * @param phStdOut The standard out handle to assign the new process. Pass
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.
181 * @param phStdErr The standard error handle to assign the new process. Pass
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.
185 * @param pszAsUser User to run the process as. Pass NULL to use the same
186 * user as the current process.
187 * Windows: Use user\@domain (UPN, User Principal Name)
188 * format to specify a domain.
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.
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.
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.
199 * @param phProcess Where to store the process handle on successful return.
200 * The content is not changed on failure. NULL is allowed.
201 *
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 *
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 */
209RTR3DECL(int) RTProcCreateEx(const char *pszExec, const char * const *papszArgs, RTENV hEnv, uint32_t fFlags,
210 PCRTHANDLE phStdIn, PCRTHANDLE phStdOut, PCRTHANDLE phStdErr, const char *pszAsUser,
211 const char *pszPassword, void *pvExtraData, PRTPROCESS phProcess);
212
213/** @name RTProcCreate and RTProcCreateEx flags
214 * @{ */
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)
221/** Don't show the started process.
222 * This is a Windows (and maybe OS/2) concept, do not use on other platforms. */
223#define RTPROC_FLAGS_HIDDEN RT_BIT(1)
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. */
228#define RTPROC_FLAGS_SERVICE RT_BIT(2)
229/** Suppress changing the process contract id for the child process
230 * on Solaris. Without this flag the contract id is always changed, as that's
231 * the more frequently used case. */
232#define RTPROC_FLAGS_SAME_CONTRACT RT_BIT(3)
233/** Load user profile data when executing a process.
234 * This redefines the meaning of RTENV_DEFAULT to the profile environment. See
235 * also RTPROC_FLAGS_ONLY_BASIC_PROFILE */
236#define RTPROC_FLAGS_PROFILE RT_BIT(4)
237/** Create process without a console window.
238 * This is a Windows (and OS/2) concept, do not use on other platforms. */
239#define RTPROC_FLAGS_NO_WINDOW RT_BIT(5)
240/** Search the PATH for the executable. */
241#define RTPROC_FLAGS_SEARCH_PATH RT_BIT(6)
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)
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)
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)
256/** For use with RTPROC_FLAGS_SERVICE to specify a desired session ID
257 * (Windows only, ignored elsewhere). The @a pvExtraData argument points to
258 * a uint32_t containing the session ID, UINT32_MAX means any session.
259 * Cannot be set with RTPROC_FLAGS_TOKEN_SUPPLIED or RTPROC_FLAGS_CWD. */
260#define RTPROC_FLAGS_DESIRED_SESSION_ID RT_BIT(11)
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)
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)
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.
269 * Cannot be set with RTPROC_FLAGS_DESIRED_SESSION_ID or RTPROC_FLAGS_CWD.
270 * Windows only flag, ignored everywhere else. */
271#define RTPROC_FLAGS_TOKEN_SUPPLIED RT_BIT(14)
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)
277
278/** Valid flag mask. */
279#define RTPROC_FLAGS_VALID_MASK UINT32_C(0xffff)
280/** @} */
281
282
283/**
284 * Process exit reason.
285 */
286typedef 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 */
299typedef 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. */
307typedef RTPROCSTATUS *PRTPROCSTATUS;
308/** Pointer to a const process exit status structure. */
309typedef 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
316/** Don't block, just check if the process have exited. */
317#define RTPROCWAIT_FLAGS_NOBLOCK 1
318/** @} */
319
320/**
321 * Waits for a process, resumes on interruption.
322 *
323 * @returns VINF_SUCCESS when the status code for the process was collected and
324 * put in *pProcStatus.
325 * @returns VERR_PROCESS_NOT_FOUND if the specified process wasn't found.
326 * @returns VERR_PROCESS_RUNNING when the RTPROCWAIT_FLAGS_NOBLOCK and the
327 * process haven't exited yet.
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.
332 * Optional.
333 */
334RTR3DECL(int) RTProcWait(RTPROCESS Process, unsigned fFlags, PRTPROCSTATUS pProcStatus);
335
336/**
337 * Waits for a process, returns on interruption.
338 *
339 * @returns VINF_SUCCESS when the status code for the process was collected and
340 * put in *pProcStatus.
341 * @returns VERR_PROCESS_NOT_FOUND if the specified process wasn't found.
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.
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.
350 * Optional.
351 */
352RTR3DECL(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 */
360RTR3DECL(int) RTProcTerminate(RTPROCESS Process);
361
362/**
363 * Gets the processor affinity mask of the current process.
364 *
365 * @returns The affinity mask.
366 */
367RTR3DECL(uint64_t) RTProcGetAffinityMask(void);
368
369/**
370 * Gets the short process name.
371 *
372 * @returns Pointer to read-only name string.
373 * @note IPRT must've been initialized or the string will be empty.
374 */
375RTR3DECL(const char *) RTProcShortName(void);
376
377/**
378 * Gets the path to the executable image of the current process.
379 *
380 * @returns Pointer to read-only path string.
381 * @note IPRT must've been initialized or the string will be empty.
382 */
383RTR3DECL(const char *) RTProcExecutablePath(void);
384
385/**
386 * Gets a copy of the path to the executable image of the current process.
387 *
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.
392 * @note IPRT must've been initialized or the string will be empty.
393 */
394RTR3DECL(char *) RTProcGetExecutablePath(char *pszExecPath, size_t cbExecPath);
395
396/**
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 *
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.
414 */
415RTR3DECL(int) RTProcDaemonize(const char * const *papszArgs, const char *pszDaemonizedOpt);
416
417/**
418 * Daemonize the current process, making it a background process. The current
419 * process will exit if daemonizing is successful.
420 *
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 *
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 */
431RTR3DECL(int) RTProcDaemonizeUsingFork(bool fNoChDir, bool fNoClose, const char *pszPidfile);
432
433/**
434 * Check if the given process is running on the system.
435 *
436 * This check is case sensitive on most systems, except for Windows, OS/2 and
437 * Darwin.
438 *
439 * @returns true if the process is running & false otherwise.
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.
444 */
445RTR3DECL(bool) RTProcIsRunningByName(const char *pszName);
446
447/**
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 */
454RTR3DECL(int) RTProcQueryParent(RTPROCESS hProcess, PRTPROCESS phParent);
455
456/**
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.
462 * NIL_PROCESS is an alias for the current process.
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 */
469RTR3DECL(int) RTProcQueryUsername(RTPROCESS hProcess, char *pszUser, size_t cbUser, size_t *pcbUser);
470
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 */
479RTR3DECL(int) RTProcQueryUsernameA(RTPROCESS hProcess, char **ppszUser);
480
481#endif /* IN_RING3 */
482
483/** @} */
484
485RT_C_DECLS_END
486
487#endif /* !IPRT_INCLUDED_process_h */
488
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette