VirtualBox

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

Last change on this file since 91991 was 82968, checked in by vboxsync, 5 years ago

Copyright year updates by scm.

  • 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-2020 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