VirtualBox

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

Last change on this file since 66601 was 62473, checked in by vboxsync, 8 years ago

(C) 2016

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 16.2 KB
Line 
1/** @file
2 * IPRT - Process Management.
3 */
4
5/*
6 * Copyright (C) 2006-2016 Oracle Corporation
7 *
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.
15 *
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.
21 *
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.
24 */
25
26#ifndef ___iprt_process_h
27#define ___iprt_process_h
28
29#include <iprt/cdefs.h>
30#include <iprt/types.h>
31
32RT_C_DECLS_BEGIN
33
34/** @defgroup grp_rt_process RTProc - Process Management
35 * @ingroup grp_rt
36 * @{
37 */
38
39
40/**
41 * Process priority.
42 *
43 * The process priority is used to select how scheduling properties
44 * are assigned to the different thread types (see THREADTYPE).
45 *
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.
50 */
51typedef enum RTPROCPRIORITY
52{
53 /** Invalid priority. */
54 RTPROCPRIORITY_INVALID = 0,
55 /** Default priority.
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.
59 */
60 RTPROCPRIORITY_DEFAULT,
61 /** Flat priority.
62 * Assumes a scheduling policy which puts the process at the default priority
63 * and with all thread at the same priority.
64 */
65 RTPROCPRIORITY_FLAT,
66 /** Low priority.
67 * Assumes a scheduling policy which puts the process mostly below the
68 * default priority of the host OS.
69 */
70 RTPROCPRIORITY_LOW,
71 /** Normal priority.
72 * Assume a scheduling policy which shares the CPU resources fairly with
73 * other processes running with the default priority of the host OS.
74 */
75 RTPROCPRIORITY_NORMAL,
76 /** High priority.
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.
80 */
81 RTPROCPRIORITY_HIGH,
82 /** Last priority, used for validation. */
83 RTPROCPRIORITY_LAST
84} RTPROCPRIORITY;
85
86
87/**
88 * Get the current process identifier.
89 *
90 * @returns Process identifier.
91 */
92RTDECL(RTPROCESS) RTProcSelf(void);
93
94
95#ifdef IN_RING0
96/**
97 * Get the current process handle.
98 *
99 * @returns Ring-0 process handle.
100 */
101RTR0DECL(RTR0PROCESS) RTR0ProcHandleSelf(void);
102#endif
103
104
105#ifdef IN_RING3
106
107/**
108 * Attempts to alter the priority of the current process.
109 *
110 * @returns iprt status code.
111 * @param enmPriority The new priority.
112 */
113RTR3DECL(int) RTProcSetPriority(RTPROCPRIORITY enmPriority);
114
115/**
116 * Gets the current priority of this process.
117 *
118 * @returns The priority (see RTPROCPRIORITY).
119 */
120RTR3DECL(RTPROCPRIORITY) RTProcGetPriority(void);
121
122/**
123 * Create a child process.
124 *
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.
132 */
133RTR3DECL(int) RTProcCreate(const char *pszExec, const char * const *papszArgs, RTENV Env, unsigned fFlags, PRTPROCESS pProcess);
134
135
136/**
137 * Create a child process.
138 *
139 * @returns IPRT status code.
140 *
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
146 * process.
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
151 * guest.
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
155 * guest.
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
159 * guest.
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.
169 *
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
172 * platforms.
173 *
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.
176 */
177RTR3DECL(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);
180
181/** @name RTProcCreate and RTProcCreateEx flags
182 * @{ */
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).
185 *
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
195 * platforms. */
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
206 * environment. */
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)
223/** @} */
224
225
226/**
227 * Process exit reason.
228 */
229typedef enum RTPROCEXITREASON
230{
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
237} RTPROCEXITREASON;
238
239/**
240 * Process exit status.
241 */
242typedef struct RTPROCSTATUS
243{
244 /** The process exit status if the exit was a normal one. */
245 int iStatus;
246 /** The reason the process terminated. */
247 RTPROCEXITREASON enmReason;
248} RTPROCSTATUS;
249/** Pointer to a process exit status structure. */
250typedef RTPROCSTATUS *PRTPROCSTATUS;
251/** Pointer to a const process exit status structure. */
252typedef const RTPROCSTATUS *PCRTPROCSTATUS;
253
254
255/** Flags for RTProcWait().
256 * @{ */
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
261/** @} */
262
263/**
264 * Waits for a process, resumes on interruption.
265 *
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.
271 *
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.
275 * Optional.
276 */
277RTR3DECL(int) RTProcWait(RTPROCESS Process, unsigned fFlags, PRTPROCSTATUS pProcStatus);
278
279/**
280 * Waits for a process, returns on interruption.
281 *
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.
289 *
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.
293 * Optional.
294 */
295RTR3DECL(int) RTProcWaitNoResume(RTPROCESS Process, unsigned fFlags, PRTPROCSTATUS pProcStatus);
296
297/**
298 * Terminates (kills) a running process.
299 *
300 * @returns IPRT status code.
301 * @param Process The process to terminate.
302 */
303RTR3DECL(int) RTProcTerminate(RTPROCESS Process);
304
305/**
306 * Gets the processor affinity mask of the current process.
307 *
308 * @returns The affinity mask.
309 */
310RTR3DECL(uint64_t) RTProcGetAffinityMask(void);
311
312/**
313 * Gets the short process name.
314 *
315 * @returns Pointer to read-only name string.
316 */
317RTR3DECL(const char *) RTProcShortName(void);
318
319/**
320 * Gets the path to the executable image of the current process.
321 *
322 * @returns pszExecPath on success. NULL on buffer overflow or other errors.
323 *
324 * @param pszExecPath Where to store the path.
325 * @param cbExecPath The size of the buffer.
326 */
327RTR3DECL(char *) RTProcGetExecutablePath(char *pszExecPath, size_t cbExecPath);
328
329/**
330 * Daemonize the current process, making it a background process.
331 *
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.
337 *
338 * The new process will have the standard handles directed to/from the
339 * bitbucket.
340 *
341 * @returns IPRT status code. On success it is normal for the caller to exit
342 * the process by returning from main().
343 *
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.
347 */
348RTR3DECL(int) RTProcDaemonize(const char * const *papszArgs, const char *pszDaemonizedOpt);
349
350/**
351 * Daemonize the current process, making it a background process. The current
352 * process will exit if daemonizing is successful.
353 *
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.
357 *
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.
363 */
364RTR3DECL(int) RTProcDaemonizeUsingFork(bool fNoChDir, bool fNoClose, const char *pszPidfile);
365
366/**
367 * Check if the given process is running on the system.
368 *
369 * This check is case sensitive on most systems, except for Windows, OS/2 and
370 * Darwin.
371 *
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
376 * matched.
377 */
378RTR3DECL(bool) RTProcIsRunningByName(const char *pszName);
379
380/**
381 * Queries the parent process ID.
382 *
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.
386 */
387RTR3DECL(int) RTProcQueryParent(RTPROCESS hProcess, PRTPROCESS phParent);
388
389/**
390 * Query the username of the given process.
391 *
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
400 * is returned.
401 */
402RTR3DECL(int) RTProcQueryUsername(RTPROCESS hProcess, char *pszUser, size_t cbUser, size_t *pcbUser);
403
404/**
405 * Query the username of the given process allocating the string for the username.
406 *
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().
411 */
412RTR3DECL(int) RTProcQueryUsernameA(RTPROCESS hProcess, char **ppszUser);
413
414#endif /* IN_RING3 */
415
416/** @} */
417
418RT_C_DECLS_END
419
420#endif
421
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