VirtualBox

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

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