VirtualBox

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

Last change on this file since 13830 was 11337, checked in by vboxsync, 16 years ago

Runtime: new function for daemonizing, implemented on posix systems only so far.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 8.1 KB
Line 
1/** @file
2 * IPRT - Process Management.
3 */
4
5/*
6 * Copyright (C) 2006-2007 Sun Microsystems, Inc.
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 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
26 * Clara, CA 95054 USA or visit http://www.sun.com if you need
27 * additional information or have any questions.
28 */
29
30#ifndef ___iprt_process_h
31#define ___iprt_process_h
32
33#include <iprt/cdefs.h>
34#include <iprt/types.h>
35
36__BEGIN_DECLS
37
38/** @defgroup grp_rt_process RTProc - Process Management
39 * @ingroup grp_rt
40 * @{
41 */
42
43
44/**
45 * Process priority.
46 *
47 * The process priority is used to select how scheduling properties
48 * are assigned to the different thread types (see THREADTYPE).
49 *
50 * In addition to using the policy assigned to the process at startup (DEFAULT)
51 * it is possible to change the process priority at runtime. This allows for
52 * a GUI, resource manager or admin to adjust the general priorty of a task
53 * without upsetting the fine-tuned priority of the threads within.
54 */
55typedef enum RTPROCPRIORITY
56{
57 /** Invalid priority. */
58 RTPROCPRIORITY_INVALID = 0,
59 /** Default priority.
60 * Derive the schedulding policy from the priority of the RTR3Init()
61 * and RTProcSetPriority() callers and the rights the process have
62 * to alter its own priority.
63 */
64 RTPROCPRIORITY_DEFAULT,
65 /** Flat priority.
66 * Assumes a scheduling policy which puts the process at the default priority
67 * and with all thread at the same priority.
68 */
69 RTPROCPRIORITY_FLAT,
70 /** Low priority.
71 * Assumes a scheduling policy which puts the process mostly below the
72 * default priority of the host OS.
73 */
74 RTPROCPRIORITY_LOW,
75 /** Normal priority.
76 * Assume a scheduling policy which shares the cpu resources fairly with
77 * other processes running with the default priority of the host OS.
78 */
79 RTPROCPRIORITY_NORMAL,
80 /** High priority.
81 * Assumes a scheduling policy which puts the task above the default
82 * priority of the host OS. This policy might easily cause other tasks
83 * in the system to starve.
84 */
85 RTPROCPRIORITY_HIGH,
86 /** Last priority, used for validation. */
87 RTPROCPRIORITY_LAST
88} RTPROCPRIORITY;
89
90
91/**
92 * Get the current process identifier.
93 *
94 * @returns Process identifier.
95 */
96RTDECL(RTPROCESS) RTProcSelf(void);
97
98
99#ifdef IN_RING0
100/**
101 * Get the current process handle.
102 *
103 * @returns Ring-0 process handle.
104 */
105RTR0DECL(RTR0PROCESS) RTR0ProcHandleSelf(void);
106#endif
107
108
109#ifdef IN_RING3
110
111/**
112 * Attempts to alter the priority of the current process.
113 *
114 * @returns iprt status code.
115 * @param enmPriority The new priority.
116 */
117RTR3DECL(int) RTProcSetPriority(RTPROCPRIORITY enmPriority);
118
119/**
120 * Gets the current priority of this process.
121 *
122 * @returns The priority (see RTPROCPRIORITY).
123 */
124RTR3DECL(RTPROCPRIORITY) RTProcGetPriority(void);
125
126/**
127 * Create a child process.
128 *
129 * @returns iprt status code.
130 * @param pszExec Executable image to use to create the child process.
131 * @param papszArgs Pointer to an array of arguments to the child. The array terminated by an entry containing NULL.
132 * @param Env Handle to the environment block for the child.
133 * @param fFlags Flags. This is currently reserved and must be 0.
134 * @param pProcess Where to store the process identifier on successful return.
135 * The content is not changed on failure. NULL is allowed.
136 */
137RTR3DECL(int) RTProcCreate(const char *pszExec, const char * const *papszArgs, RTENV Env, unsigned fFlags, PRTPROCESS pProcess);
138
139/**
140 * Process exit reason.
141 */
142typedef enum RTPROCEXITREASON
143{
144 /** Normal exit. iStatus contains the exit code. */
145 RTPROCEXITREASON_NORMAL = 1,
146 /** Any abnormal exit. iStatus is undefined. */
147 RTPROCEXITREASON_ABEND,
148 /** Killed by a signal. The iStatus field contains the signal number. */
149 RTPROCEXITREASON_SIGNAL
150} RTPROCEXITREASON;
151
152/**
153 * Process exit status.
154 */
155typedef struct RTPROCSTATUS
156{
157 /** The process exit status if the exit was a normal one. */
158 int iStatus;
159 /** The reason the process terminated. */
160 RTPROCEXITREASON enmReason;
161} RTPROCSTATUS;
162/** Pointer to a process exit status structure. */
163typedef RTPROCSTATUS *PRTPROCSTATUS;
164/** Pointer to a const process exit status structure. */
165typedef const RTPROCSTATUS *PCRTPROCSTATUS;
166
167
168/** Flags for RTProcWait().
169 * @{ */
170/** Block indefinitly waiting for the process to exit. */
171#define RTPROCWAIT_FLAGS_BLOCK 0
172/** Don't block, just check if the process have exitted. */
173#define RTPROCWAIT_FLAGS_NOBLOCK 1
174/** @} */
175
176/**
177 * Waits for a process, resumes on interruption.
178 *
179 * @returns VINF_SUCCESS when the status code for the process was collected and put in *pProcStatus.
180 * @returns VERR_PROCESS_NOT_FOUND if the specified process wasn't found.
181 * @returns VERR_PROCESS_RUNNING when the RTPROCWAIT_FLAG_NOBLOCK and the process haven't exitted yet.
182 *
183 * @param Process The process to wait for.
184 * @param fFlags The wait flags, any of the RTPROCWAIT_FLAGS_ \#defines.
185 * @param pProcStatus Where to store the exit status on success.
186 */
187RTR3DECL(int) RTProcWait(RTPROCESS Process, unsigned fFlags, PRTPROCSTATUS pProcStatus);
188
189/**
190 * Waits for a process, returns on interruption.
191 *
192 * @returns VINF_SUCCESS when the status code for the process was collected and put in *pProcStatus.
193 * @returns VERR_PROCESS_NOT_FOUND if the specified process wasn't found.
194 * @returns VERR_PROCESS_RUNNING when the RTPROCWAIT_FLAG_NOBLOCK and the process haven't exitted yet.
195 * @returns VERR_INTERRUPTED when the wait was interrupted by the arrival of a signal or other async event.
196 *
197 * @param Process The process to wait for.
198 * @param fFlags The wait flags, any of the RTPROCWAIT_FLAGS_ \#defines.
199 * @param pProcStatus Where to store the exit status on success.
200 */
201RTR3DECL(int) RTProcWaitNoResume(RTPROCESS Process, unsigned fFlags, PRTPROCSTATUS pProcStatus);
202
203/**
204 * Terminates (kills) a running process.
205 *
206 * @returns IPRT status code.
207 * @param Process The process to terminate.
208 */
209RTR3DECL(int) RTProcTerminate(RTPROCESS Process);
210
211/**
212 * Gets the processor affinity mask of the current process.
213 *
214 * @returns The affinity mask.
215 */
216RTR3DECL(uint64_t) RTProcGetAffinityMask(void);
217
218/**
219 * Gets the executable image name of the current process.
220 *
221 *
222 * @returns pszExecName on success. NULL on buffer overflow or other errors.
223 *
224 * @param pszExecName Where to store the name.
225 * @param cchExecName The size of the buffer.
226 */
227RTR3DECL(char *) RTProcGetExecutableName(char *pszExecName, size_t cchExecName);
228
229/**
230 * Daemonize the current process, making it a background process. The current
231 * process will exit if daemonizing is successful.
232 *
233 * @returns iprt status code.
234 * @param fNoChDir Pass false to change working directory to "/".
235 * @param fNoClose Pass false to redirect standard file streams to the null device.
236 * @param pszPidfile Path to a file to write the process id of the daemon
237 * process to. Daemonizing will fail if this file already
238 * exists or cannot be written. May be NULL.
239 */
240RTR3DECL(int) RTProcDaemonize(bool fNoChDir, bool fNoClose, const char *pszPidfile);
241
242#endif /* IN_RING3 */
243
244/** @} */
245
246__END_DECLS
247
248#endif
249
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