VirtualBox

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

Last change on this file since 49894 was 44528, checked in by vboxsync, 12 years ago

header (C) fixes

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