2 * IPRT - Process Management.
6 * Copyright (C) 2006-2016 Oracle Corporation
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
26 #ifndef ___iprt_process_h
27 #define ___iprt_process_h
29 #include <iprt/cdefs.h>
30 #include <iprt/types.h>
34 /** @defgroup grp_rt_process RTProc - Process Management
43 * The process priority is used to select how scheduling properties
44 * are assigned to the different thread types (see THREADTYPE).
46 * In addition to using the policy assigned to the process at startup (DEFAULT)
47 * it is possible to change the process priority at runtime. This allows for
48 * a GUI, resource manager or admin to adjust the general priority of a task
49 * without upsetting the fine-tuned priority of the threads within.
51 typedef enum RTPROCPRIORITY
53 /** Invalid priority. */
54 RTPROCPRIORITY_INVALID
= 0,
56 * Derive the scheduling policy from the priority of the RTR3Init()
57 * and RTProcSetPriority() callers and the rights the process have
58 * to alter its own priority.
60 RTPROCPRIORITY_DEFAULT
,
62 * Assumes a scheduling policy which puts the process at the default priority
63 * and with all thread at the same priority.
67 * Assumes a scheduling policy which puts the process mostly below the
68 * default priority of the host OS.
72 * Assume a scheduling policy which shares the CPU resources fairly with
73 * other processes running with the default priority of the host OS.
75 RTPROCPRIORITY_NORMAL
,
77 * Assumes a scheduling policy which puts the task above the default
78 * priority of the host OS. This policy might easily cause other tasks
79 * in the system to starve.
82 /** Last priority, used for validation. */
88 * Get the current process identifier.
90 * @returns Process identifier.
92 RTDECL(RTPROCESS
) RTProcSelf(void);
97 * Get the current process handle.
99 * @returns Ring-0 process handle.
101 RTR0DECL(RTR0PROCESS
) RTR0ProcHandleSelf(void);
108 * Attempts to alter the priority of the current process.
110 * @returns iprt status code.
111 * @param enmPriority The new priority.
113 RTR3DECL(int) RTProcSetPriority(RTPROCPRIORITY enmPriority
);
116 * Gets the current priority of this process.
118 * @returns The priority (see RTPROCPRIORITY).
120 RTR3DECL(RTPROCPRIORITY
) RTProcGetPriority(void);
123 * Create a child process.
125 * @returns iprt status code.
126 * @param pszExec Executable image to use to create the child process.
127 * @param papszArgs Pointer to an array of arguments to the child. The array terminated by an entry containing NULL.
128 * @param Env Handle to the environment block for the child.
129 * @param fFlags Flags, one of the RTPROC_FLAGS_* defines.
130 * @param pProcess Where to store the process identifier on successful return.
131 * The content is not changed on failure. NULL is allowed.
133 RTR3DECL(int) RTProcCreate(const char *pszExec
, const char * const *papszArgs
, RTENV Env
, unsigned fFlags
, PRTPROCESS pProcess
);
137 * Create a child process.
139 * @returns IPRT status code.
141 * @param pszExec Executable image to use to create the child process.
142 * @param papszArgs Pointer to an array of arguments to the child. The
143 * array terminated by an entry containing NULL.
144 * @param hEnv Handle to the environment block for the child. Pass
145 * RTENV_DEFAULT to use the environment of the current
147 * @param fFlags Flags, one of the RTPROC_FLAGS_* defines.
148 * @param phStdIn The standard in handle to assign the new process. Pass
149 * NULL to use the same as the current process. If the
150 * handle is NIL, we'll close the standard input of the
152 * @param phStdOut The standard out handle to assign the new process. Pass
153 * NULL to use the same as the current process. If the
154 * handle is NIL, we'll close the standard output of the
156 * @param phStdErr The standard error handle to assign the new process. Pass
157 * NULL to use the same as the current process. If the
158 * handle is NIL, we'll close the standard error of the
160 * @param pszAsUser User to run the process as. Pass NULL to use the same
161 * user as the current process.
162 * Windows: Use user\@domain (UPN, User Principal Name)
163 * format to specify a domain.
164 * @param pszPassword Password to use to authenticate @a pszAsUser. Must be
165 * NULL wif pszAsUser is NULL. Whether this is actually
166 * used or not depends on the platform.
167 * @param phProcess Where to store the process handle on successful return.
168 * The content is not changed on failure. NULL is allowed.
170 * @remarks The handles does not have to be created as inheritable, but it
171 * doesn't hurt if they are as it may avoid race conditions on some
174 * @remarks The as-user feature isn't supported/implemented on all platforms and
175 * will cause a-yet-to-be-determined-error-status on these.
177 RTR3DECL(int) RTProcCreateEx(const char *pszExec
, const char * const *papszArgs
, RTENV hEnv
, uint32_t fFlags
,
178 PCRTHANDLE phStdIn
, PCRTHANDLE phStdOut
, PCRTHANDLE phStdErr
, const char *pszAsUser
,
179 const char *pszPassword
, PRTPROCESS phProcess
);
181 /** @name RTProcCreate and RTProcCreateEx flags
183 /** Detach the child process from the parents process tree and process group,
184 * session or/and console (depends on the platform what's done applicable).
186 * The new process will not be a direct decendent of the parent and it will not
187 * be possible to wait for it, i.e. @a phProcess shall be NULL. */
188 #define RTPROC_FLAGS_DETACHED RT_BIT(0)
189 /** Don't show the started process.
190 * This is a Windows (and maybe OS/2) concept, do not use on other platforms. */
191 #define RTPROC_FLAGS_HIDDEN RT_BIT(1)
192 /** Use special code path for starting child processes from a service (daemon).
193 * This is a windows concept for dealing with the so called "Session 0"
194 * isolation which was introduced with Windows Vista. Do not use on other
196 #define RTPROC_FLAGS_SERVICE RT_BIT(2)
197 /** Suppress changing the process contract id for the child process
198 * on Solaris. Without this flag the contract id is always changed, as that's
199 * the more frequently used case. */
200 #define RTPROC_FLAGS_SAME_CONTRACT RT_BIT(3)
201 /** Load user profile data when executing a process.
202 * This redefines the meaning of RTENV_DEFAULT to the profile environment.
203 * @remarks On non-windows platforms, the resulting environment maybe very
204 * different from what you see in your shell. Among other reasons,
205 * we cannot run shell profile scripts which typically sets up the
207 #define RTPROC_FLAGS_PROFILE RT_BIT(4)
208 /** Create process without a console window.
209 * This is a Windows (and OS/2) concept, do not use on other platforms. */
210 #define RTPROC_FLAGS_NO_WINDOW RT_BIT(5)
211 /** Search the PATH for the executable. */
212 #define RTPROC_FLAGS_SEARCH_PATH RT_BIT(6)
213 /** Don't quote and escape arguments on Windows and similar platforms where a
214 * command line is passed to the child process instead of an argument vector,
215 * just join up argv with a space between each. Ignored on platforms
216 * passing argument the vector. */
217 #define RTPROC_FLAGS_UNQUOTED_ARGS RT_BIT(7)
218 /** Consider hEnv an environment change record to be applied to RTENV_DEFAULT.
219 * If hEnv is RTENV_DEFAULT, the flag has no effect. */
220 #define RTPROC_FLAGS_ENV_CHANGE_RECORD RT_BIT(8)
221 /** Valid flag mask. */
222 #define RTPROC_FLAGS_VALID_MASK UINT32_C(0x1ff)
227 * Process exit reason.
229 typedef enum RTPROCEXITREASON
231 /** Normal exit. iStatus contains the exit code. */
232 RTPROCEXITREASON_NORMAL
= 1,
233 /** Any abnormal exit. iStatus is undefined. */
234 RTPROCEXITREASON_ABEND
,
235 /** Killed by a signal. The iStatus field contains the signal number. */
236 RTPROCEXITREASON_SIGNAL
240 * Process exit status.
242 typedef struct RTPROCSTATUS
244 /** The process exit status if the exit was a normal one. */
246 /** The reason the process terminated. */
247 RTPROCEXITREASON enmReason
;
249 /** Pointer to a process exit status structure. */
250 typedef RTPROCSTATUS
*PRTPROCSTATUS
;
251 /** Pointer to a const process exit status structure. */
252 typedef const RTPROCSTATUS
*PCRTPROCSTATUS
;
255 /** Flags for RTProcWait().
257 /** Block indefinitly waiting for the process to exit. */
258 #define RTPROCWAIT_FLAGS_BLOCK 0
259 /** Don't block, just check if the process have exited. */
260 #define RTPROCWAIT_FLAGS_NOBLOCK 1
264 * Waits for a process, resumes on interruption.
266 * @returns VINF_SUCCESS when the status code for the process was collected and
267 * put in *pProcStatus.
268 * @returns VERR_PROCESS_NOT_FOUND if the specified process wasn't found.
269 * @returns VERR_PROCESS_RUNNING when the RTPROCWAIT_FLAGS_NOBLOCK and the
270 * process haven't exited yet.
272 * @param Process The process to wait for.
273 * @param fFlags The wait flags, any of the RTPROCWAIT_FLAGS_ \#defines.
274 * @param pProcStatus Where to store the exit status on success.
277 RTR3DECL(int) RTProcWait(RTPROCESS Process
, unsigned fFlags
, PRTPROCSTATUS pProcStatus
);
280 * Waits for a process, returns on interruption.
282 * @returns VINF_SUCCESS when the status code for the process was collected and
283 * put in *pProcStatus.
284 * @returns VERR_PROCESS_NOT_FOUND if the specified process wasn't found.
285 * @returns VERR_PROCESS_RUNNING when the RTPROCWAIT_FLAGS_NOBLOCK and the
286 * process haven't exited yet.
287 * @returns VERR_INTERRUPTED when the wait was interrupted by the arrival of a
288 * signal or other async event.
290 * @param Process The process to wait for.
291 * @param fFlags The wait flags, any of the RTPROCWAIT_FLAGS_ \#defines.
292 * @param pProcStatus Where to store the exit status on success.
295 RTR3DECL(int) RTProcWaitNoResume(RTPROCESS Process
, unsigned fFlags
, PRTPROCSTATUS pProcStatus
);
298 * Terminates (kills) a running process.
300 * @returns IPRT status code.
301 * @param Process The process to terminate.
303 RTR3DECL(int) RTProcTerminate(RTPROCESS Process
);
306 * Gets the processor affinity mask of the current process.
308 * @returns The affinity mask.
310 RTR3DECL(uint64_t) RTProcGetAffinityMask(void);
313 * Gets the short process name.
315 * @returns Pointer to read-only name string.
317 RTR3DECL(const char *) RTProcShortName(void);
320 * Gets the path to the executable image of the current process.
322 * @returns pszExecPath on success. NULL on buffer overflow or other errors.
324 * @param pszExecPath Where to store the path.
325 * @param cbExecPath The size of the buffer.
327 RTR3DECL(char *) RTProcGetExecutablePath(char *pszExecPath
, size_t cbExecPath
);
330 * Daemonize the current process, making it a background process.
332 * The way this work is that it will spawn a detached / backgrounded /
333 * daemonized / call-it-what-you-want process that isn't a direct child of the
334 * current process. The spawned will have the same arguments a the caller,
335 * except that the @a pszDaemonizedOpt is appended to prevent that the new
336 * process calls this API again.
338 * The new process will have the standard handles directed to/from the
341 * @returns IPRT status code. On success it is normal for the caller to exit
342 * the process by returning from main().
344 * @param papszArgs The argument vector of the calling process.
345 * @param pszDaemonizedOpt The daemonized option. This is appended to the
346 * end of the parameter list of the daemonized process.
348 RTR3DECL(int) RTProcDaemonize(const char * const *papszArgs
, const char *pszDaemonizedOpt
);
351 * Daemonize the current process, making it a background process. The current
352 * process will exit if daemonizing is successful.
354 * @returns IPRT status code. On success it will only return in the child
355 * process, the parent will exit. On failure, it will return in the
356 * parent process and no child has been spawned.
358 * @param fNoChDir Pass false to change working directory to "/".
359 * @param fNoClose Pass false to redirect standard file streams to the null device.
360 * @param pszPidfile Path to a file to write the process id of the daemon
361 * process to. Daemonizing will fail if this file already
362 * exists or cannot be written. May be NULL.
364 RTR3DECL(int) RTProcDaemonizeUsingFork(bool fNoChDir
, bool fNoClose
, const char *pszPidfile
);
367 * Check if the given process is running on the system.
369 * This check is case sensitive on most systems, except for Windows, OS/2 and
372 * @returns true if the process is running & false otherwise.
373 * @param pszName Process name to search for. If no path is given only the
374 * filename part of the running process set will be
375 * matched. If a path is specified, the full path will be
378 RTR3DECL(bool) RTProcIsRunningByName(const char *pszName
);
381 * Queries the parent process ID.
383 * @returns IPRT status code
384 * @param hProcess The process to query the parent of.
385 * @param phParent Where to return the parent process ID.
387 RTR3DECL(int) RTProcQueryParent(RTPROCESS hProcess
, PRTPROCESS phParent
);
390 * Query the username of the given process.
392 * @returns IPRT status code.
393 * @retval VERR_BUFFER_OVERFLOW if the given buffer size is to small for the username.
394 * @param hProcess The process handle to query the username for.
395 * NIL_PROCESS is an alias for the current process.
396 * @param pszUser Where to store the user name on success.
397 * @param cbUser The size of the user name buffer.
398 * @param pcbUser Where to store the username length on success
399 * or the required buffer size if VERR_BUFFER_OVERFLOW
402 RTR3DECL(int) RTProcQueryUsername(RTPROCESS hProcess
, char *pszUser
, size_t cbUser
, size_t *pcbUser
);
405 * Query the username of the given process allocating the string for the username.
407 * @returns IPRT status code.
408 * @param hProcess The process handle to query the username for.
409 * @param ppszUser Where to store the pointer to the string containing
410 * the username on success. Free with RTStrFree().
412 RTR3DECL(int) RTProcQueryUsernameA(RTPROCESS hProcess
, char **ppszUser
);
414 #endif /* IN_RING3 */