VirtualBox

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

Last change on this file since 21751 was 20374, checked in by vboxsync, 16 years ago

*: s/RT_\(BEGIN|END\)_DECLS/RT_C_DECLS_\1/g

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 8.9 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
36RT_C_DECLS_BEGIN
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 priority 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 scheduling 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, one of the RTPROC_FLAGS_* defines.
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/** @name RTProcCreate flags
140 * @{ */
141/** Daemonize the child process, without changing the directory.
142 * @remarks Not implemented on all platforms yet... */
143#define RTPROC_FLAGS_DAEMONIZE RT_BIT(0)
144/** @} */
145
146
147/**
148 * Process exit reason.
149 */
150typedef enum RTPROCEXITREASON
151{
152 /** Normal exit. iStatus contains the exit code. */
153 RTPROCEXITREASON_NORMAL = 1,
154 /** Any abnormal exit. iStatus is undefined. */
155 RTPROCEXITREASON_ABEND,
156 /** Killed by a signal. The iStatus field contains the signal number. */
157 RTPROCEXITREASON_SIGNAL
158} RTPROCEXITREASON;
159
160/**
161 * Process exit status.
162 */
163typedef struct RTPROCSTATUS
164{
165 /** The process exit status if the exit was a normal one. */
166 int iStatus;
167 /** The reason the process terminated. */
168 RTPROCEXITREASON enmReason;
169} RTPROCSTATUS;
170/** Pointer to a process exit status structure. */
171typedef RTPROCSTATUS *PRTPROCSTATUS;
172/** Pointer to a const process exit status structure. */
173typedef const RTPROCSTATUS *PCRTPROCSTATUS;
174
175
176/** Flags for RTProcWait().
177 * @{ */
178/** Block indefinitly waiting for the process to exit. */
179#define RTPROCWAIT_FLAGS_BLOCK 0
180/** Don't block, just check if the process have exited. */
181#define RTPROCWAIT_FLAGS_NOBLOCK 1
182/** @} */
183
184/**
185 * Waits for a process, resumes on interruption.
186 *
187 * @returns VINF_SUCCESS when the status code for the process was collected and put in *pProcStatus.
188 * @returns VERR_PROCESS_NOT_FOUND if the specified process wasn't found.
189 * @returns VERR_PROCESS_RUNNING when the RTPROCWAIT_FLAG_NOBLOCK and the process haven't exited yet.
190 *
191 * @param Process The process to wait for.
192 * @param fFlags The wait flags, any of the RTPROCWAIT_FLAGS_ \#defines.
193 * @param pProcStatus Where to store the exit status on success.
194 */
195RTR3DECL(int) RTProcWait(RTPROCESS Process, unsigned fFlags, PRTPROCSTATUS pProcStatus);
196
197/**
198 * Waits for a process, returns on interruption.
199 *
200 * @returns VINF_SUCCESS when the status code for the process was collected and put in *pProcStatus.
201 * @returns VERR_PROCESS_NOT_FOUND if the specified process wasn't found.
202 * @returns VERR_PROCESS_RUNNING when the RTPROCWAIT_FLAG_NOBLOCK and the process haven't exited yet.
203 * @returns VERR_INTERRUPTED when the wait was interrupted by the arrival of a signal or other async event.
204 *
205 * @param Process The process to wait for.
206 * @param fFlags The wait flags, any of the RTPROCWAIT_FLAGS_ \#defines.
207 * @param pProcStatus Where to store the exit status on success.
208 */
209RTR3DECL(int) RTProcWaitNoResume(RTPROCESS Process, unsigned fFlags, PRTPROCSTATUS pProcStatus);
210
211/**
212 * Terminates (kills) a running process.
213 *
214 * @returns IPRT status code.
215 * @param Process The process to terminate.
216 */
217RTR3DECL(int) RTProcTerminate(RTPROCESS Process);
218
219/**
220 * Gets the processor affinity mask of the current process.
221 *
222 * @returns The affinity mask.
223 */
224RTR3DECL(uint64_t) RTProcGetAffinityMask(void);
225
226/**
227 * Gets the executable image name of the current process.
228 *
229 *
230 * @returns pszExecName on success. NULL on buffer overflow or other errors.
231 *
232 * @param pszExecName Where to store the name.
233 * @param cchExecName The size of the buffer.
234 */
235RTR3DECL(char *) RTProcGetExecutableName(char *pszExecName, size_t cchExecName);
236
237/**
238 * Daemonize the current process, making it a background process. The current
239 * process will exit if daemonizing is successful.
240 *
241 * @returns iprt status code.
242 * @param fNoChDir Pass false to change working directory to "/".
243 * @param fNoClose Pass false to redirect standard file streams to the null device.
244 * @param pszPidfile Path to a file to write the process id of the daemon
245 * process to. Daemonizing will fail if this file already
246 * exists or cannot be written. May be NULL.
247 */
248RTR3DECL(int) RTProcDaemonize(bool fNoChDir, bool fNoClose, const char *pszPidfile);
249
250/**
251 * Check if the given process is running on the system.
252 *
253 * This check is case sensitive on most systems, except for Windows, OS/2 and
254 * Darwin.
255 *
256 * @returns true if the process is running & false otherwise.
257 * @param pszName Process name to search for. If no path is given only the
258 * filename part of the running process set will be
259 * matched. If a path is specified, the full path will be
260 * matched.
261 */
262RTR3DECL(bool) RTProcIsRunningByName(const char *pszName);
263
264#endif /* IN_RING3 */
265
266/** @} */
267
268RT_C_DECLS_END
269
270#endif
271
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