VirtualBox

source: vbox/trunk/include/iprt/env.h@ 34575

Last change on this file since 34575 was 28800, checked in by vboxsync, 15 years ago

Automated rebranding to Oracle copyright/license strings via filemuncher

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 8.0 KB
Line 
1/** @file
2 * IPRT - Process Environment Strings.
3 */
4
5/*
6 * Copyright (C) 2006-2007 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_env_h
27#define ___iprt_env_h
28
29#include <iprt/cdefs.h>
30#include <iprt/types.h>
31
32RT_C_DECLS_BEGIN
33
34/** @defgroup grp_rt_env RTEnv - Process Environment Strings
35 * @ingroup grp_rt
36 * @{
37 */
38
39#ifdef IN_RING3
40
41/** Special handle that indicates the default process environment. */
42#define RTENV_DEFAULT ((RTENV)~(uintptr_t)0)
43
44/**
45 * Creates an empty environment block.
46 *
47 * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
48 *
49 * @param pEnv Where to store the handle of the new environment block.
50 */
51RTDECL(int) RTEnvCreate(PRTENV pEnv);
52
53/**
54 * Creates an environment block and fill it with variables from the given
55 * environment array.
56 *
57 * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
58 *
59 * @param pEnv Where to store the handle of the new environment block.
60 * @param EnvToClone The environment to clone.
61 */
62RTDECL(int) RTEnvClone(PRTENV pEnv, RTENV EnvToClone);
63
64/**
65 * Destroys an environment block.
66 *
67 * @returns IPRT status code.
68 *
69 * @param Env Environment block handle.
70 * Both RTENV_DEFAULT and NIL_RTENV are silently ignored.
71 */
72RTDECL(int) RTEnvDestroy(RTENV Env);
73
74/**
75 * Get the execve/spawnve/main envp.
76 *
77 * All returned strings are in the current process' codepage.
78 * This array is only valid until the next RTEnv call.
79 *
80 * @returns Pointer to the raw array of environment variables.
81 * @returns NULL if Env is NULL or invalid.
82 *
83 * @param Env Environment block handle.
84 */
85RTDECL(char const * const *) RTEnvGetExecEnvP(RTENV Env);
86
87/**
88 * Get a sorted, UTF-16 environment block for CreateProcess.
89 *
90 * @returns IPRT status code.
91 *
92 * @param hEnv Environment block handle.
93 * @param ppwszzBlock Where to return the environment block. This must be
94 * freed by calling RTEnvFreeUtf16Block.
95 */
96RTDECL(int) RTEnvQueryUtf16Block(RTENV hEnv, PRTUTF16 *ppwszzBlock);
97
98/**
99 * Frees an environment block returned by RTEnvGetUtf16Block().
100 *
101 * @param pwszzBlock What RTEnvGetUtf16Block returned. NULL is ignored.
102 */
103RTDECL(void) RTEnvFreeUtf16Block(PRTUTF16 pwszzBlock);
104
105/**
106 * Checks if an environment variable exists in the default environment block.
107 *
108 * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
109 *
110 * @param pszVar The environment variable name.
111 * @remark WARNING! The current implementation does not perform the appropriate
112 * codeset conversion. We'll figure this out when it becomes necessary.
113 */
114RTDECL(bool) RTEnvExist(const char *pszVar);
115
116/**
117 * Checks if an environment variable exists in a specific environment block.
118 *
119 * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
120 *
121 * @param Env The environment handle.
122 * @param pszVar The environment variable name.
123 */
124RTDECL(bool) RTEnvExistEx(RTENV Env, const char *pszVar);
125
126/**
127 * Gets an environment variable from the default environment block. (getenv).
128 *
129 * The caller is responsible for ensuring that nobody changes the environment
130 * while it's using the returned string pointer!
131 *
132 * @returns Pointer to read only string on success, NULL if the variable wasn't found.
133 *
134 * @param pszVar The environment variable name.
135 *
136 * @remark WARNING! The current implementation does not perform the appropriate
137 * codeset conversion. We'll figure this out when it becomes necessary.
138 */
139RTDECL(const char *) RTEnvGet(const char *pszVar);
140
141/**
142 * Gets an environment variable in a specific environment block.
143 *
144 * @returns IPRT status code.
145 * @retval VERR_ENV_VAR_NOT_FOUND if the variable was not found.
146 *
147 * @param Env The environment handle.
148 * @param pszVar The environment variable name.
149 * @param pszValue Where to put the buffer.
150 * @param cbValue The size of the value buffer.
151 * @param pcchActual Returns the actual value string length. Optional.
152 */
153RTDECL(int) RTEnvGetEx(RTENV Env, const char *pszVar, char *pszValue, size_t cbValue, size_t *pcchActual);
154
155/**
156 * Puts an variable=value string into the environment (putenv).
157 *
158 * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
159 *
160 * @param pszVarEqualValue The variable '=' value string. If the value and '=' is
161 * omitted, the variable is removed from the environment.
162 *
163 * @remark Don't assume the value is copied.
164 * @remark WARNING! The current implementation does not perform the appropriate
165 * codeset conversion. We'll figure this out when it becomes necessary.
166 */
167RTDECL(int) RTEnvPut(const char *pszVarEqualValue);
168
169/**
170 * Puts a copy of the passed in 'variable=value' string into the environment block.
171 *
172 * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
173 *
174 * @param Env Handle of the environment block.
175 * @param pszVarEqualValue The variable '=' value string. If the value and '=' is
176 * omitted, the variable is removed from the environment.
177 */
178RTDECL(int) RTEnvPutEx(RTENV Env, const char *pszVarEqualValue);
179
180/**
181 * Sets an environment variable (setenv(,,1)).
182 *
183 * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
184 *
185 * @param pszVar The environment variable name.
186 * @param pszValue The environment variable value.
187 *
188 * @remark WARNING! The current implementation does not perform the appropriate
189 * codeset conversion. We'll figure this out when it becomes necessary.
190 */
191RTDECL(int) RTEnvSet(const char *pszVar, const char *pszValue);
192
193/**
194 * Sets an environment variable (setenv(,,1)).
195 *
196 * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
197 *
198 * @param Env The environment handle.
199 * @param pszVar The environment variable name.
200 * @param pszValue The environment variable value.
201 */
202RTDECL(int) RTEnvSetEx(RTENV Env, const char *pszVar, const char *pszValue);
203
204/**
205 * Removes an environment variable from the default environment block.
206 *
207 * @returns IPRT status code.
208 * @returns VINF_ENV_VAR_NOT_FOUND if the variable was not found.
209 *
210 * @param pszVar The environment variable name.
211 *
212 * @remark WARNING! The current implementation does not perform the appropriate
213 * codeset conversion. We'll figure this out when it becomes necessary.
214 */
215RTDECL(int) RTEnvUnset(const char *pszVar);
216
217/**
218 * Removes an environment variable from the specified environment block.
219 *
220 * @returns IPRT status code.
221 * @returns VINF_ENV_VAR_NOT_FOUND if the variable was not found.
222 *
223 * @param Env The environment handle.
224 * @param pszVar The environment variable name.
225 */
226RTDECL(int) RTEnvUnsetEx(RTENV Env, const char *pszVar);
227
228/**
229 * Duplicates the value of a environment variable if it exists.
230 *
231 * @returns Pointer to a string containing the value, free it using RTStrFree.
232 * NULL if the variable was not found or we're out of memory.
233 *
234 * @param Env The environment handle.
235 * @param pszVar The environment variable name.
236 */
237RTDECL(char *) RTEnvDupEx(RTENV Env, const char *pszVar);
238
239#endif /* IN_RING3 */
240
241/** @} */
242
243RT_C_DECLS_END
244
245#endif
246
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