VirtualBox

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

Last change on this file since 80874 was 80827, checked in by vboxsync, 5 years ago

IPRT: Added RTEnvCreateEx and RTEnvCreateChangeRecordEx so flags can be specified when creating custom environments. Defined one flag RTENV_CREATE_F_ALLOW_EQUAL_FIRST_IN_VAR for accomodating windows style environment variables (used for CWD by driver letter). The flag is set by default on windows hosts, however it does not work for the default environment due to CRT limitations.

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