VirtualBox

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

Last change on this file since 47942 was 44528, checked in by vboxsync, 12 years ago

header (C) fixes

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 15.0 KB
Line 
1/** @file
2 * IPRT - Process Management.
3 */
4
5/*
6 * Copyright (C) 2006-2012 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 format to specify a domain.
163 * @param pszPassword Password to use to authenticate @a pszAsUser. Must be
164 * NULL wif pszAsUser is NULL. Whether this is actually
165 * used or not depends on the platform.
166 * @param phProcess Where to store the process handle on successful return.
167 * The content is not changed on failure. NULL is allowed.
168 *
169 * @remarks The handles does not have to be created as inheritable, but it
170 * doesn't hurt if they are as it may avoid race conditions on some
171 * platforms.
172 *
173 * @remarks The as-user feature isn't supported/implemented on all platforms and
174 * will cause a-yet-to-be-determined-error-status on these.
175 */
176RTR3DECL(int) RTProcCreateEx(const char *pszExec, const char * const *papszArgs, RTENV hEnv, uint32_t fFlags,
177 PCRTHANDLE phStdIn, PCRTHANDLE phStdOut, PCRTHANDLE phStdErr, const char *pszAsUser,
178 const char *pszPassword, PRTPROCESS phProcess);
179
180/** @name RTProcCreate and RTProcCreateEx flags
181 * @{ */
182/** Detach the child process from the parents process tree and process group,
183 * session or/and console (depends on the platform what's done applicable).
184 *
185 * The new process will not be a direct decendent of the parent and it will not
186 * be possible to wait for it, i.e. @a phProcess shall be NULL. */
187#define RTPROC_FLAGS_DETACHED RT_BIT(0)
188/** Don't show the started process.
189 * This is a window (and maybe OS/2) concept, do not use on other platforms. */
190#define RTPROC_FLAGS_HIDDEN RT_BIT(1)
191/** Use special code path for starting child processes from a service (daemon).
192 * This is a windows concept for dealing with the so called "Session 0"
193 * isolation which was introduced with Windows Vista. Do not use on other
194 * platforms. */
195#define RTPROC_FLAGS_SERVICE RT_BIT(2)
196/** Suppress changing the process contract id for the child process
197 * on Solaris. Without this flag the contract id is always changed, as that's
198 * the more frequently used case. */
199#define RTPROC_FLAGS_SAME_CONTRACT RT_BIT(3)
200/** Do not load user profile data when executing a process.
201 * This bit at the moment only is valid on Windows. */
202#define RTPROC_FLAGS_NO_PROFILE RT_BIT(4)
203/** Create process without a console window.
204 * This is a Windows (and OS/2) concept, do not use on other platforms. */
205#define RTPROC_FLAGS_NO_WINDOW RT_BIT(5)
206/** Search the PATH for the executable. */
207#define RTPROC_FLAGS_SEARCH_PATH RT_BIT(6)
208
209/** @} */
210
211
212/**
213 * Process exit reason.
214 */
215typedef enum RTPROCEXITREASON
216{
217 /** Normal exit. iStatus contains the exit code. */
218 RTPROCEXITREASON_NORMAL = 1,
219 /** Any abnormal exit. iStatus is undefined. */
220 RTPROCEXITREASON_ABEND,
221 /** Killed by a signal. The iStatus field contains the signal number. */
222 RTPROCEXITREASON_SIGNAL
223} RTPROCEXITREASON;
224
225/**
226 * Process exit status.
227 */
228typedef struct RTPROCSTATUS
229{
230 /** The process exit status if the exit was a normal one. */
231 int iStatus;
232 /** The reason the process terminated. */
233 RTPROCEXITREASON enmReason;
234} RTPROCSTATUS;
235/** Pointer to a process exit status structure. */
236typedef RTPROCSTATUS *PRTPROCSTATUS;
237/** Pointer to a const process exit status structure. */
238typedef const RTPROCSTATUS *PCRTPROCSTATUS;
239
240
241/** Flags for RTProcWait().
242 * @{ */
243/** Block indefinitly waiting for the process to exit. */
244#define RTPROCWAIT_FLAGS_BLOCK 0
245/** Don't block, just check if the process have exited. */
246#define RTPROCWAIT_FLAGS_NOBLOCK 1
247/** @} */
248
249/**
250 * Waits for a process, resumes on interruption.
251 *
252 * @returns VINF_SUCCESS when the status code for the process was collected and
253 * put in *pProcStatus.
254 * @returns VERR_PROCESS_NOT_FOUND if the specified process wasn't found.
255 * @returns VERR_PROCESS_RUNNING when the RTPROCWAIT_FLAGS_NOBLOCK and the
256 * process haven't exited yet.
257 *
258 * @param Process The process to wait for.
259 * @param fFlags The wait flags, any of the RTPROCWAIT_FLAGS_ \#defines.
260 * @param pProcStatus Where to store the exit status on success.
261 * Optional.
262 */
263RTR3DECL(int) RTProcWait(RTPROCESS Process, unsigned fFlags, PRTPROCSTATUS pProcStatus);
264
265/**
266 * Waits for a process, returns on interruption.
267 *
268 * @returns VINF_SUCCESS when the status code for the process was collected and
269 * put in *pProcStatus.
270 * @returns VERR_PROCESS_NOT_FOUND if the specified process wasn't found.
271 * @returns VERR_PROCESS_RUNNING when the RTPROCWAIT_FLAGS_NOBLOCK and the
272 * process haven't exited yet.
273 * @returns VERR_INTERRUPTED when the wait was interrupted by the arrival of a
274 * signal or other async event.
275 *
276 * @param Process The process to wait for.
277 * @param fFlags The wait flags, any of the RTPROCWAIT_FLAGS_ \#defines.
278 * @param pProcStatus Where to store the exit status on success.
279 * Optional.
280 */
281RTR3DECL(int) RTProcWaitNoResume(RTPROCESS Process, unsigned fFlags, PRTPROCSTATUS pProcStatus);
282
283/**
284 * Terminates (kills) a running process.
285 *
286 * @returns IPRT status code.
287 * @param Process The process to terminate.
288 */
289RTR3DECL(int) RTProcTerminate(RTPROCESS Process);
290
291/**
292 * Gets the processor affinity mask of the current process.
293 *
294 * @returns The affinity mask.
295 */
296RTR3DECL(uint64_t) RTProcGetAffinityMask(void);
297
298/**
299 * Gets the short process name.
300 *
301 * @returns Pointer to read-only name string.
302 */
303RTR3DECL(const char *) RTProcShortName(void);
304
305/**
306 * Gets the path to the executable image of the current process.
307 *
308 * @returns pszExecPath on success. NULL on buffer overflow or other errors.
309 *
310 * @param pszExecPath Where to store the path.
311 * @param cbExecPath The size of the buffer.
312 */
313RTR3DECL(char *) RTProcGetExecutablePath(char *pszExecPath, size_t cbExecPath);
314
315/**
316 * Daemonize the current process, making it a background process.
317 *
318 * The way this work is that it will spawn a detached / backgrounded /
319 * daemonized / call-it-what-you-want process that isn't a direct child of the
320 * current process. The spawned will have the same arguments a the caller,
321 * except that the @a pszDaemonizedOpt is appended to prevent that the new
322 * process calls this API again.
323 *
324 * The new process will have the standard handles directed to/from the
325 * bitbucket.
326 *
327 * @returns IPRT status code. On success it is normal for the caller to exit
328 * the process by returning from main().
329 *
330 * @param papszArgs The argument vector of the calling process.
331 * @param pszDaemonized The daemonized option. This is appended to the end
332 * of the parameter list of the daemonized process.
333 */
334RTR3DECL(int) RTProcDaemonize(const char * const *papszArgs, const char *pszDaemonizedOpt);
335
336/**
337 * Daemonize the current process, making it a background process. The current
338 * process will exit if daemonizing is successful.
339 *
340 * @returns IPRT status code. On success it will only return in the child
341 * process, the parent will exit. On failure, it will return in the
342 * parent process and no child has been spawned.
343 *
344 * @param fNoChDir Pass false to change working directory to "/".
345 * @param fNoClose Pass false to redirect standard file streams to the null device.
346 * @param pszPidfile Path to a file to write the process id of the daemon
347 * process to. Daemonizing will fail if this file already
348 * exists or cannot be written. May be NULL.
349 */
350RTR3DECL(int) RTProcDaemonizeUsingFork(bool fNoChDir, bool fNoClose, const char *pszPidfile);
351
352/**
353 * Check if the given process is running on the system.
354 *
355 * This check is case sensitive on most systems, except for Windows, OS/2 and
356 * Darwin.
357 *
358 * @returns true if the process is running & false otherwise.
359 * @param pszName Process name to search for. If no path is given only the
360 * filename part of the running process set will be
361 * matched. If a path is specified, the full path will be
362 * matched.
363 */
364RTR3DECL(bool) RTProcIsRunningByName(const char *pszName);
365
366/**
367 * Query the username of the given process.
368 *
369 * @returns IPRT status code.
370 * @retval VERR_BUFFER_OVERFLOW if the given buffer size is to small for the username.
371 * @param hProcess The process handle to query the username for.
372 * @param pszUser Where to store the user name on success.
373 * @param cbUser The size of the user name buffer.
374 * @param pcbUser Where to store the username length on success
375 * or the required buffer size if VERR_BUFFER_OVERFLOW
376 * is returned.
377 */
378RTR3DECL(int) RTProcQueryUsername(RTPROCESS hProcess, char *pszUser, size_t cbUser,
379 size_t *pcbUser);
380
381/**
382 * Query the username of the given process allocating the string for the username.
383 *
384 * @returns IPRT status code.
385 * @param hProcess The process handle to query the username for.
386 * @param ppszUser Where to store the pointer to the string containing
387 * the username on success. Free with RTStrFree().
388 */
389RTR3DECL(int) RTProcQueryUsernameA(RTPROCESS hProcess, char **ppszUser);
390
391#endif /* IN_RING3 */
392
393/** @} */
394
395RT_C_DECLS_END
396
397#endif
398
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