process.h revision c9eb3a5d1f667186ac07e211b3f0b003d6ba5f31
* IPRT - Process Management. * Copyright (C) 2006-2007 Sun Microsystems, Inc. * This file is part of VirtualBox Open Source Edition (OSE), as * you can redistribute it and/or modify it under the terms of the GNU * General Public License (GPL) as published by the Free Software * Foundation, in version 2 as it comes in the "COPYING" file of the * VirtualBox OSE distribution. VirtualBox OSE is distributed in the * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind. * The contents of this file may alternatively be used under the terms * of the Common Development and Distribution License Version 1.0 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the * VirtualBox OSE distribution, in which case the provisions of the * CDDL are applicable instead of those of the GPL. * You may elect to license modified versions of this file under the * terms and conditions of either the GPL or the CDDL or both. * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa * additional information or have any questions. /** @defgroup grp_rt_process RTProc - Process Management * The process priority is used to select how scheduling properties * are assigned to the different thread types (see THREADTYPE). * In addition to using the policy assigned to the process at startup (DEFAULT) * it is possible to change the process priority at runtime. This allows for * a GUI, resource manager or admin to adjust the general priority of a task * without upsetting the fine-tuned priority of the threads within. * Derive the scheduling policy from the priority of the RTR3Init() * and RTProcSetPriority() callers and the rights the process have * to alter its own priority. * Assumes a scheduling policy which puts the process at the default priority * and with all thread at the same priority. * Assumes a scheduling policy which puts the process mostly below the * default priority of the host OS. * Assume a scheduling policy which shares the CPU resources fairly with * other processes running with the default priority of the host OS. * Assumes a scheduling policy which puts the task above the default * priority of the host OS. This policy might easily cause other tasks * in the system to starve. /** Last priority, used for validation. */ * Get the current process identifier. * @returns Process identifier. * Get the current process handle. * @returns Ring-0 process handle. * Attempts to alter the priority of the current process. * @returns iprt status code. * @param enmPriority The new priority. * Gets the current priority of this process. * @returns The priority (see RTPROCPRIORITY). * Create a child process. * @returns iprt status code. * @param pszExec Executable image to use to create the child process. * @param papszArgs Pointer to an array of arguments to the child. The array terminated by an entry containing NULL. * @param Env Handle to the environment block for the child. * @param fFlags Flags, one of the RTPROC_FLAGS_* defines. * @param pProcess Where to store the process identifier on successful return. * The content is not changed on failure. NULL is allowed. * Create a child process. * @returns IPRT status code. * @param pszExec Executable image to use to create the child process. * @param papszArgs Pointer to an array of arguments to the child. The * array terminated by an entry containing NULL. * @param hEnv Handle to the environment block for the child. Pass * RTENV_DEFAULT to use the environment of the current * @param fFlags Flags, one of the RTPROC_FLAGS_* defines. * @param phStdIn The standard in handle to assign the new process. Pass * NULL to use the same as the current process. * @param phStdOut The standard out handle to assign the new process. Pass * NULL to use the same as the current process. * @param phStdErr The standard error handle to assign the new process. Pass * NULL to use the same as the current process. * @param pszAsUser User to run the process as. Pass NULL to use the same * user as the current process. * @param phProcess Where to store the process handle on successful return. * The content is not changed on failure. NULL is allowed. * will cause a-yet-to-be-determined-error-status on these. /** @name RTProcCreate and RTProcCreateEx flags /** Daemonize the child process, without changing the directory. * @remarks Not implemented on all platforms yet... */ /** Normal exit. iStatus contains the exit code. */ /** Any abnormal exit. iStatus is undefined. */ /** Killed by a signal. The iStatus field contains the signal number. */ /** The process exit status if the exit was a normal one. */ /** The reason the process terminated. */ /** Pointer to a process exit status structure. */ /** Pointer to a const process exit status structure. */ /** Flags for RTProcWait(). /** Block indefinitly waiting for the process to exit. */ /** Don't block, just check if the process have exited. */ * Waits for a process, resumes on interruption. * @returns VINF_SUCCESS when the status code for the process was collected and put in *pProcStatus. * @returns VERR_PROCESS_NOT_FOUND if the specified process wasn't found. * @returns VERR_PROCESS_RUNNING when the RTPROCWAIT_FLAG_NOBLOCK and the process haven't exited yet. * @param Process The process to wait for. * @param fFlags The wait flags, any of the RTPROCWAIT_FLAGS_ \#defines. * @param pProcStatus Where to store the exit status on success. * Waits for a process, returns on interruption. * @returns VINF_SUCCESS when the status code for the process was collected and put in *pProcStatus. * @returns VERR_PROCESS_NOT_FOUND if the specified process wasn't found. * @returns VERR_PROCESS_RUNNING when the RTPROCWAIT_FLAG_NOBLOCK and the process haven't exited yet. * @returns VERR_INTERRUPTED when the wait was interrupted by the arrival of a signal or other async event. * @param Process The process to wait for. * @param fFlags The wait flags, any of the RTPROCWAIT_FLAGS_ \#defines. * @param pProcStatus Where to store the exit status on success. * Terminates (kills) a running process. * @returns IPRT status code. * @param Process The process to terminate. * Gets the processor affinity mask of the current process. * @returns The affinity mask. * Gets the executable image name of the current process. * @returns pszExecName on success. NULL on buffer overflow or other errors. * @param pszExecName Where to store the name. * @param cchExecName The size of the buffer. * Daemonize the current process, making it a background process. The current * process will exit if daemonizing is successful. * @returns iprt status code. * @param fNoChDir Pass false to change working directory to "/". * @param fNoClose Pass false to redirect standard file streams to the null device. * @param pszPidfile Path to a file to write the process id of the daemon * process to. Daemonizing will fail if this file already * exists or cannot be written. May be NULL. * Check if the given process is running on the system. * This check is case sensitive on most systems, except for Windows, OS/2 and * @returns true if the process is running & false otherwise. * @param pszName Process name to search for. If no path is given only the * filename part of the running process set will be * matched. If a path is specified, the full path will be