VirtualBox

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

Last change on this file since 68716 was 62473, checked in by vboxsync, 8 years ago

(C) 2016

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 14.6 KB
Line 
1/** @file
2 * IPRT - Process Environment Strings.
3 */
4
5/*
6 * Copyright (C) 2006-2016 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.
58 * @retval VWRN_ENV_NOT_FULLY_TRANSLATED may be returned when passing
59 * RTENV_DEFAULT and one or more of the environment variables have
60 * codeset incompatibilities. The problematic variables will be
61 * ignored and not included in the clone, thus the clone will have
62 * fewer variables.
63 * @retval VERR_NO_MEMORY
64 * @retval VERR_NO_STR_MEMORY
65 * @retval VERR_INVALID_HANDLE
66 *
67 * @param pEnv Where to store the handle of the new environment block.
68 * @param EnvToClone The environment to clone.
69 */
70RTDECL(int) RTEnvClone(PRTENV pEnv, RTENV EnvToClone);
71
72/**
73 * Creates an environment block from an UTF-16 environment raw block.
74 *
75 * This is the reverse of RTEnvQueryUtf16Block.
76 *
77 * @returns IPRT status code.
78 * @retval VERR_NO_MEMORY
79 * @retval VERR_NO_STR_MEMORY
80 *
81 * @param phEnv Where to store the handle of the new environment block.
82 * @param pwszzBlock List of zero terminated string end with a zero length
83 * string (or two zero terminators if you prefer). The
84 * strings are on the RTPutEnv format (VAR=VALUE), except
85 * they are all expected to include an equal sign.
86 * @param fFlags Flags served for the future.
87 */
88RTDECL(int) RTEnvCloneUtf16Block(PRTENV phEnv, PCRTUTF16 pwszzBlock, uint32_t fFlags);
89
90/**
91 * Destroys an environment block.
92 *
93 * @returns IPRT status code.
94 *
95 * @param Env Environment block handle.
96 * Both RTENV_DEFAULT and NIL_RTENV are silently ignored.
97 */
98RTDECL(int) RTEnvDestroy(RTENV Env);
99
100/**
101 * Resets the environment block to contain zero variables.
102 *
103 * @returns IPRT status code.
104 *
105 * @param hEnv Environment block handle. RTENV_DEFAULT is not supported.
106 */
107RTDECL(int) RTEnvReset(RTENV hEnv);
108
109/**
110 * Get the execve/spawnve/main envp.
111 *
112 * All returned strings are in the current process' codepage.
113 * This array is only valid until the next RTEnv call.
114 *
115 * @returns Pointer to the raw array of environment variables.
116 * @returns NULL if Env is NULL or invalid.
117 *
118 * @param Env Environment block handle.
119 * @todo This needs to change to return a copy of the env vars like
120 * RTEnvQueryUtf16Block does!
121 */
122RTDECL(char const * const *) RTEnvGetExecEnvP(RTENV Env);
123
124/**
125 * Get a sorted, UTF-16 environment block for CreateProcess.
126 *
127 * @returns IPRT status code.
128 *
129 * @param hEnv Environment block handle.
130 * @param ppwszzBlock Where to return the environment block. This must be
131 * freed by calling RTEnvFreeUtf16Block.
132 */
133RTDECL(int) RTEnvQueryUtf16Block(RTENV hEnv, PRTUTF16 *ppwszzBlock);
134
135/**
136 * Frees an environment block returned by RTEnvGetUtf16Block().
137 *
138 * @param pwszzBlock What RTEnvGetUtf16Block returned. NULL is ignored.
139 */
140RTDECL(void) RTEnvFreeUtf16Block(PRTUTF16 pwszzBlock);
141
142/**
143 * Get a sorted, UTF-8 environment block.
144 *
145 * The environment block is a sequence of putenv formatted ("NAME=VALUE" or
146 * "NAME") zero terminated strings ending with an empty string (i.e. last string
147 * has two zeros).
148 *
149 * @returns IPRT status code.
150 *
151 * @param hEnv Environment block handle.
152 * @param fSorted Whether to sort it, this will affect @a hEnv.
153 * @param ppszzBlock Where to return the environment block. This must be
154 * freed by calling RTEnvFreeUtf8Block.
155 * @param pcbBlock Where to return the size of the block. Optional.
156 */
157RTDECL(int) RTEnvQueryUtf8Block(RTENV hEnv, bool fSorted, char **ppszzBlock, size_t *pcbBlock);
158
159/**
160 * Frees an environment block returned by RTEnvGetUtf8Block().
161 *
162 * @param pszzBlock What RTEnvGetUtf8Block returned. NULL is ignored.
163 */
164RTDECL(void) RTEnvFreeUtf8Block(char *pszzBlock);
165
166/**
167 * Checks if an environment variable exists in the default environment block.
168 *
169 * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
170 *
171 * @param pszVar The environment variable name.
172 * @remark WARNING! The current implementation does not perform the appropriate
173 * codeset conversion. We'll figure this out when it becomes necessary.
174 */
175RTDECL(bool) RTEnvExist(const char *pszVar);
176RTDECL(bool) RTEnvExistsBad(const char *pszVar);
177RTDECL(bool) RTEnvExistsUtf8(const char *pszVar);
178
179/**
180 * Checks if an environment variable exists in a specific environment block.
181 *
182 * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
183 *
184 * @param Env The environment handle.
185 * @param pszVar The environment variable name.
186 */
187RTDECL(bool) RTEnvExistEx(RTENV Env, const char *pszVar);
188
189/**
190 * Gets an environment variable from the default environment block. (getenv).
191 *
192 * The caller is responsible for ensuring that nobody changes the environment
193 * while it's using the returned string pointer!
194 *
195 * @returns Pointer to read only string on success, NULL if the variable wasn't found.
196 *
197 * @param pszVar The environment variable name.
198 *
199 * @remark WARNING! The current implementation does not perform the appropriate
200 * codeset conversion. We'll figure this out when it becomes necessary.
201 */
202RTDECL(const char *) RTEnvGet(const char *pszVar);
203RTDECL(const char *) RTEnvGetBad(const char *pszVar);
204RTDECL(int) RTEnvGetUtf8(const char *pszVar, char *pszValue, size_t cbValue, size_t *pcchActual);
205
206/**
207 * Gets an environment variable in a specific environment block.
208 *
209 * @returns IPRT status code.
210 * @retval VERR_ENV_VAR_NOT_FOUND if the variable was not found.
211 * @retval VERR_ENV_VAR_UNSET if @a hEnv is an environment change record and
212 * the variable has been recorded as unset.
213 *
214 * @param hEnv The environment handle.
215 * @param pszVar The environment variable name.
216 * @param pszValue Where to put the buffer.
217 * @param cbValue The size of the value buffer.
218 * @param pcchActual Returns the actual value string length. Optional.
219 */
220RTDECL(int) RTEnvGetEx(RTENV hEnv, const char *pszVar, char *pszValue, size_t cbValue, size_t *pcchActual);
221
222/**
223 * Puts an variable=value string into the environment (putenv).
224 *
225 * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
226 *
227 * @param pszVarEqualValue The variable '=' value string. If the value and '=' is
228 * omitted, the variable is removed from the environment.
229 *
230 * @remark Don't assume the value is copied.
231 * @remark WARNING! The current implementation does not perform the appropriate
232 * codeset conversion. We'll figure this out when it becomes necessary.
233 */
234RTDECL(int) RTEnvPut(const char *pszVarEqualValue);
235RTDECL(int) RTEnvPutBad(const char *pszVarEqualValue);
236RTDECL(int) RTEnvPutUtf8(const char *pszVarEqualValue);
237
238/**
239 * Puts a copy of the passed in 'variable=value' string into the environment block.
240 *
241 * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
242 *
243 * @param Env Handle of the environment block.
244 * @param pszVarEqualValue The variable '=' value string. If the value and '=' is
245 * omitted, the variable is removed from the environment.
246 */
247RTDECL(int) RTEnvPutEx(RTENV Env, const char *pszVarEqualValue);
248
249/**
250 * Sets an environment variable (setenv(,,1)).
251 *
252 * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
253 *
254 * @param pszVar The environment variable name.
255 * @param pszValue The environment variable value.
256 *
257 * @remark WARNING! The current implementation does not perform the appropriate
258 * codeset conversion. We'll figure this out when it becomes necessary.
259 */
260RTDECL(int) RTEnvSet(const char *pszVar, const char *pszValue);
261RTDECL(int) RTEnvSetBad(const char *pszVar, const char *pszValue);
262RTDECL(int) RTEnvSetUtf8(const char *pszVar, const char *pszValue);
263
264/**
265 * Sets an environment variable (setenv(,,1)).
266 *
267 * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
268 *
269 * @param Env The environment handle.
270 * @param pszVar The environment variable name.
271 * @param pszValue The environment variable value.
272 */
273RTDECL(int) RTEnvSetEx(RTENV Env, const char *pszVar, const char *pszValue);
274
275/**
276 * Removes an environment variable from the default environment block.
277 *
278 * @returns IPRT status code.
279 * @returns VINF_ENV_VAR_NOT_FOUND if the variable was not found.
280 *
281 * @param pszVar The environment variable name.
282 *
283 * @remark WARNING! The current implementation does not perform the appropriate
284 * codeset conversion. We'll figure this out when it becomes necessary.
285 */
286RTDECL(int) RTEnvUnset(const char *pszVar);
287RTDECL(int) RTEnvUnsetBad(const char *pszVar);
288RTDECL(int) RTEnvUnsetUtf8(const char *pszVar);
289
290/**
291 * Removes an environment variable from the specified environment block.
292 *
293 * @returns IPRT status code.
294 * @returns VINF_ENV_VAR_NOT_FOUND if the variable was not found.
295 *
296 * @param Env The environment handle.
297 * @param pszVar The environment variable name.
298 */
299RTDECL(int) RTEnvUnsetEx(RTENV Env, const char *pszVar);
300
301/**
302 * Duplicates the value of a environment variable if it exists.
303 *
304 * @returns Pointer to a string containing the value, free it using RTStrFree.
305 * NULL if the variable was not found or we're out of memory.
306 *
307 * @param Env The environment handle.
308 * @param pszVar The environment variable name.
309 */
310RTDECL(char *) RTEnvDupEx(RTENV Env, const char *pszVar);
311
312/**
313 * Counts the variables in the environment.
314 *
315 * @returns Number of variables in the environment. UINT32_MAX on error.
316 * @param hEnv The environment handle.
317 * RTENV_DEFAULT is currently not accepted.
318 */
319RTDECL(uint32_t) RTEnvCountEx(RTENV hEnv);
320
321/**
322 * Queries an environment variable by it's index.
323 *
324 * This can be used together with RTEnvCount to enumerate the environment block.
325 *
326 * @returns IPRT status code.
327 * @retval VERR_ENV_VAR_NOT_FOUND if the index is out of bounds, output buffers
328 * untouched.
329 * @retval VERR_BUFFER_OVERFLOW if one of the buffers are too small. We'll
330 * fill it with as much we can in RTStrCopy fashion.
331 * @retval VINF_ENV_VAR_UNSET if @a hEnv is an environment change record and
332 * the variable at @a iVar is recorded as being unset.
333 *
334 * @param hEnv The environment handle.
335 * RTENV_DEFAULT is currently not accepted.
336 * @param iVar The variable index.
337 * @param pszVar Variable name buffer.
338 * @param cbVar The size of the variable name buffer.
339 * @param pszValue Value buffer.
340 * @param cbValue The size of the value buffer.
341 */
342RTDECL(int) RTEnvGetByIndexEx(RTENV hEnv, uint32_t iVar, char *pszVar, size_t cbVar, char *pszValue, size_t cbValue);
343
344/**
345 * Leaner and meaner version of RTEnvGetByIndexEx.
346 *
347 * This can be used together with RTEnvCount to enumerate the environment block.
348 *
349 * Use with caution as the returned pointer may change by the next call using
350 * the environment handle. Please only use this API in cases where there is no
351 * chance of races.
352 *
353 * @returns Pointer to the internal environment variable=value string on
354 * success. If @a hEnv is an environment change recordthe string may
355 * also be on the "variable" form, representing an unset operation. Do
356 * NOT change this string, it is read only!
357 *
358 * If the index is out of range on the environment handle is invalid,
359 * NULL is returned.
360 *
361 * @param hEnv The environment handle.
362 * RTENV_DEFAULT is currently not accepted.
363 * @param iVar The variable index.
364 */
365RTDECL(const char *) RTEnvGetByIndexRawEx(RTENV hEnv, uint32_t iVar);
366
367
368/**
369 * Creates an empty environment change record.
370 *
371 * This is a special environment for use with RTEnvApplyChanges and similar
372 * purposes. The
373 *
374 * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
375 *
376 * @param phEnv Where to store the handle of the new environment block.
377 */
378RTDECL(int) RTEnvCreateChangeRecord(PRTENV phEnv);
379
380/**
381 * Checks if @a hEnv is an environment change record.
382 *
383 * @returns true if it is, false if it's not or if the handle is invalid.
384 * @param hEnv The environment handle.
385 * @sa RTEnvCreateChangeRecord.
386 */
387RTDECL(bool) RTEnvIsChangeRecord(RTENV hEnv);
388
389/**
390 * Applies changes from one environment onto another.
391 *
392 * If @a hEnvChanges is a normal environment, its content is just added to @a
393 * hEnvDst, where variables in the destination can only be overwritten. However
394 * if @a hEnvChanges is a change record environment, variables in the
395 * destination can also be removed.
396 *
397 * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
398 * @param hEnvDst The destination environment.
399 * @param hEnvChanges Handle to the environment containig the changes to
400 * apply. As said, especially useful if it's a environment
401 * change record. RTENV_DEFAULT is not supported here.
402 */
403RTDECL(int) RTEnvApplyChanges(RTENV hEnvDst, RTENV hEnvChanges);
404
405#endif /* IN_RING3 */
406
407/** @} */
408
409RT_C_DECLS_END
410
411#endif
412
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