VirtualBox

Changeset 936 in vbox for trunk/include/iprt


Ignore:
Timestamp:
Feb 15, 2007 8:58:51 PM (18 years ago)
Author:
vboxsync
svn:sync-xref-src-repo-rev:
18671
Message:

RTEnv (incomplete).

File:
1 copied

Legend:

Unmodified
Added
Removed

  • trunk/include/iprt/env.h

    r880 r936  
    11/** @file
    2  * InnoTek Portable Runtime - Process Management.
     2 * InnoTek Portable Runtime - Process Environment Strings.
    33 */
    44
    … …  
    1919 */
    2020
    21 #ifndef __iprt_process_h__
    22 #define __iprt_process_h__
     21#ifndef __iprt_env_h__
     22#define __iprt_env_h__
    2323
    2424#include <iprt/cdefs.h>
    … …  
    2727__BEGIN_DECLS
    2828
    29 /** @defgroup grp_rt_process    RTProc - Process Management
     29/** @defgroup grp_rt_env    RTProc - Process Environment Strings
    3030 * @ingroup grp_rt
    3131 * @{
    3232 */
    3333
    34 
    35 /**
    36  * Process priority.
    37  *
    38  * The process priority is used to select how scheduling properties
    39  * are assigned to the different thread types (see THREADTYPE).
    40  *
    41  * In addition to using the policy assigned to the process at startup (DEFAULT)
    42  * it is possible to change the process priority at runtime. This allows for
    43  * a GUI, resource manager or admin to adjust the general priorty of a task
    44  * without upsetting the fine-tuned priority of the threads within.
    45  */
    46 typedef enum RTPROCPRIORITY
    47 {
    48     /** Invalid priority. */
    49     RTPROCPRIORITY_INVALID = 0,
    50     /** Default priority.
    51      * Derive the schedulding policy from the priority of the RTR3Init()
    52      * and RTProcSetPriority() callers and the rights the process have
    53      * to alter its own priority.
    54      */
    55     RTPROCPRIORITY_DEFAULT,
    56     /** Flat priority.
    57      * Assumes a scheduling policy which puts the process at the default priority
    58      * and with all thread at the same priority.
    59      */
    60     RTPROCPRIORITY_FLAT,
    61     /** Low priority.
    62      * Assumes a scheduling policy which puts the process mostly below the
    63      * default priority of the host OS.
    64      */
    65     RTPROCPRIORITY_LOW,
    66     /** Normal priority.
    67      * Assume a scheduling policy which shares the cpu resources fairly with
    68      * other processes running with the default priority of the host OS.
    69      */
    70     RTPROCPRIORITY_NORMAL,
    71     /** High priority.
    72      * Assumes a scheduling policy which puts the task above the default
    73      * priority of the host OS. This policy might easily cause other tasks
    74      * in the system to starve.
    75      */
    76     RTPROCPRIORITY_HIGH,
    77     /** Last priority, used for validation. */
    78     RTPROCPRIORITY_LAST
    79 } RTPROCPRIORITY;
    80 
    81 
    82 /**
    83  * Get the current process identifier.
    84  *
    85  * @returns Process identifier.
    86  */
    87 RTDECL(RTPROCESS) RTProcSelf(void);
    88 
    89 
    90 #ifdef IN_RING0
    91 /**
    92  * Get the current process handle.
    93  *
    94  * @returns Ring-0 process handle.
    95  */
    96 RTR0DECL(RTR0PROCESS) RTR0ProcHandleSelf(void);
    97 #endif
    98 
    99 
    10034#ifdef IN_RING3
    10135
    10236/**
    103  * Attempts to alter the priority of the current process.
    104  *
    105  * @returns iprt status code.
    106  * @param   enmPriority     The new priority.
     37 * Gets an environment variable (getenv).
     38 *
     39 * The caller is responsible for ensuring that nobody changes the environment
     40 * while it's using the returned string pointer!
     41 *
     42 * @returns Pointer to read only string on success, NULL if the variable wasn't found.
     43 *
     44 * @param   pszVar      The environment variable name.
    10745 */
    108 RTR3DECL(int) RTProcSetPriority(RTPROCPRIORITY enmPriority);
     46RTDECL(const char *) RTEnvGet(const char *pszVar);
    10947
    11048/**
    111  * Gets the current priority of this process.
    112  *
    113  * @returns The priority (see RTPROCPRIORITY).
     49 * Puts an variable=value string into the environment (putenv).
     50 *
     51 * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
     52 *
     53 * @param   pszVarEqualValue    The variable '=' value string. If the value and '=' is
     54 *                              omitted, the variable is removed from the environment.
    11455 */
    115 RTR3DECL(RTPROCPRIORITY) RTProcGetPriority(void);
     56RTDECL(int) RTEnvPut(const char *pszVarEqualValue);
    11657
    117 /**
    118  * Create a child process.
    119  *
    120  * @returns iprt status code.
    121  * @param   pszExec     Executable image to use to create the child process.
    122  * @param   papszArgs   Pointer to an array of arguments to the child. The array terminated by an entry containing NULL.
    123  * @param   papszEnv    Pointer to array of environment variables for the child process. An NULL entry
    124  *                      terminates the array. The variables are on the form '\<var\>=\<value\>'.
    125  *                      If NULL the environment of the process will be used.
    126  * @param   fFlags      Flags. This is currently reserved and must be 0.
    127  * @param   pProcess    Where to store the process identifier on successful return.
    128  *                      The content is not changed on failure. NULL is allowed.
    129  */
    130 RTR3DECL(int)   RTProcCreate(const char *pszExec, const char * const *papszArgs, const char * const *papszEnv, unsigned fFlags, PRTPROCESS pProcess);
    131 
    132 /**
    133  * Process exit reason.
    134  */
    135 typedef enum RTPROCEXITREASON
    136 {
    137     /** Normal exit. iStatus contains the exit code. */
    138     RTPROCEXITREASON_NORMAL = 1,
    139     /** Any abnormal exit. iStatus is undefined. */
    140     RTPROCEXITREASON_ABEND,
    141     /** Killed by a signal. The iStatus field contains the signal number. */
    142     RTPROCEXITREASON_SIGNAL
    143 } RTPROCEXITREASON;
    144 
    145 /**
    146  * Process exit status.
    147  */
    148 typedef struct RTPROCSTATUS
    149 {
    150     /** The process exit status if the exit was a normal one. */
    151     int                 iStatus;
    152     /** The reason the process terminated. */
    153     RTPROCEXITREASON    enmReason;
    154 } RTPROCSTATUS;
    155 /** Pointer to a process exit status structure. */
    156 typedef RTPROCSTATUS *PRTPROCSTATUS;
    157 /** Pointer to a const process exit status structure. */
    158 typedef const RTPROCSTATUS *PCRTPROCSTATUS;
    159 
    160 
    161 /** Flags for RTProcWait().
    162  * @{ */
    163 /** Block indefinitly waiting for the process to exit. */
    164 #define RTPROCWAIT_FLAGS_BLOCK      0
    165 /** Don't block, just check if the process have exitted. */
    166 #define RTPROCWAIT_FLAGS_NOBLOCK    1
    167 /** @} */
    168 
    169 /**
    170  * Waits for a process, resumes on interruption.
    171  *
    172  * @returns VINF_SUCCESS when the status code for the process was collected and put in *pProcStatus.
    173  * @returns VERR_PROCESS_NOT_FOUND if the specified process wasn't found.
    174  * @returns VERR_PROCESS_RUNNING when the RTPROCWAIT_FLAG_NOBLOCK and the process haven't exitted yet.
    175  *
    176  * @param   Process         The process to wait for.
    177  * @param   fFlags          The wait flags, any of the RTPROCWAIT_FLAGS_ \#defines.
    178  * @param   pProcStatus     Where to store the exit status on success.
    179  */
    180 RTR3DECL(int) RTProcWait(RTPROCESS Process, unsigned fFlags, PRTPROCSTATUS pProcStatus);
    181 
    182 /**
    183  * Waits for a process, returns on interruption.
    184  *
    185  * @returns VINF_SUCCESS when the status code for the process was collected and put in *pProcStatus.
    186  * @returns VERR_PROCESS_NOT_FOUND if the specified process wasn't found.
    187  * @returns VERR_PROCESS_RUNNING when the RTPROCWAIT_FLAG_NOBLOCK and the process haven't exitted yet.
    188  * @returns VERR_INTERRUPTED when the wait was interrupted by the arrival of a signal or other async event.
    189  *
    190  * @param   Process         The process to wait for.
    191  * @param   fFlags          The wait flags, any of the RTPROCWAIT_FLAGS_ \#defines.
    192  * @param   pProcStatus     Where to store the exit status on success.
    193  */
    194 RTR3DECL(int) RTProcWaitNoResume(RTPROCESS Process, unsigned fFlags, PRTPROCSTATUS pProcStatus);
    195 
    196 /**
    197  * Terminates (kills) a running process.
    198  *
    199  * @returns IPRT status code.
    200  * @param   Process     The process to terminate.
    201  */
    202 RTR3DECL(int) RTProcTerminate(RTPROCESS Process);
    203 
    204 /**
    205  * Gets the processor affinity mask of the current process.
    206  *
    207  * @returns The affinity mask.
    208  */
    209 RTR3DECL(uint64_t) RTProcGetAffinityMask(void);
    210 
    211 /**
    212  * Gets the executable image name of the current process.
    213  *
    214  *
    215  * @returns pszExecName on success. NULL on buffer overflow or other errors.
    216  *
    217  * @param   pszExecName     Where to store the name.
    218  * @param   cchExecName     The size of the buffer.
    219  */
    220 RTR3DECL(char *) RTProcGetExecutableName(char *pszExecName, size_t cchExecName);
     58/** @todo Add the missing environment APIs: safe, printf like, and various modifications. */
    22159
    22260#endif /* IN_RING3 */
Note: See TracChangeset for help on using the changeset viewer.

© 2025 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette