VirtualBox

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

Last change on this file since 18910 was 8245, checked in by vboxsync, 17 years ago

rebranding: IPRT files again.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 7.1 KB
Line 
1/** @file
2 * IPRT - Process Environment Strings.
3 */
4
5/*
6 * Copyright (C) 2006-2007 Sun Microsystems, Inc.
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 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
26 * Clara, CA 95054 USA or visit http://www.sun.com if you need
27 * additional information or have any questions.
28 */
29
30#ifndef ___iprt_env_h
31#define ___iprt_env_h
32
33#include <iprt/cdefs.h>
34#include <iprt/types.h>
35
36__BEGIN_DECLS
37
38/** @defgroup grp_rt_env RTProc - Process Environment Strings
39 * @ingroup grp_rt
40 * @{
41 */
42
43#ifdef IN_RING3
44
45/** Special handle that indicates the default process environment. */
46#define RTENV_DEFAULT ((RTENV)~(uintptr_t)0)
47
48/**
49 * Creates an empty environment block.
50 *
51 * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
52 *
53 * @param pEnv Where to store the handle of the new environment block.
54 */
55RTDECL(int) RTEnvCreate(PRTENV pEnv);
56
57/**
58 * Creates an environment block and fill it with variables from the given
59 * environment array.
60 *
61 * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
62 *
63 * @param pEnv Where to store the handle of the new environment block.
64 * @param EnvToClone The environment to clone.
65 */
66RTDECL(int) RTEnvClone(PRTENV pEnv, RTENV EnvToClone);
67
68/**
69 * Destroys an environment block.
70 *
71 * @returns IPRT status code.
72 *
73 * @param Env Environment block handle.
74 * Both RTENV_DEFAULT and NIL_RTENV are silently ignored.
75 */
76RTDECL(int) RTEnvDestroy(RTENV Env);
77
78/**
79 * Get the execve/spawnve/main envp.
80 *
81 * All returned strings are in the current process' codepage.
82 * This array is only valid until the next RTEnv call.
83 *
84 * @returns Pointer to the raw array of environment variables.
85 * @returns NULL if Env is NULL or invalid.
86 *
87 * @param Env Environment block handle.
88 */
89RTDECL(char const * const *) RTEnvGetExecEnvP(RTENV Env);
90
91
92/**
93 * Checks if an environment variable exists in the default environment block.
94 *
95 * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
96 *
97 * @param pszVar The environment variable name.
98 * @remark WARNING! The current implementation does not perform the appropriate
99 * codeset conversion. We'll figure this out when it becomes necessary.
100 */
101RTDECL(bool) RTEnvExist(const char *pszVar);
102
103/**
104 * Checks if an environment variable exists in a specific environment block.
105 *
106 * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
107 *
108 * @param Env The environment handle.
109 * @param pszVar The environment variable name.
110 */
111RTDECL(bool) RTEnvExistEx(RTENV Env, const char *pszVar);
112
113/**
114 * Gets an environment variable from the default environment block. (getenv).
115 *
116 * The caller is responsible for ensuring that nobody changes the environment
117 * while it's using the returned string pointer!
118 *
119 * @returns Pointer to read only string on success, NULL if the variable wasn't found.
120 *
121 * @param pszVar The environment variable name.
122 *
123 * @remark WARNING! The current implementation does not perform the appropriate
124 * codeset conversion. We'll figure this out when it becomes necessary.
125 */
126RTDECL(const char *) RTEnvGet(const char *pszVar);
127
128/**
129 * Gets an environment variable in a specific environment block.
130 *
131 * @returns IPRT status code.
132 *
133 * @param Env The environment handle.
134 * @param pszVar The environment variable name.
135 * @param pszValue Where to put the buffer.
136 * @param cbValue The size of the value buffer.
137 * @param pcchActual Returns the actual value string length. Optional.
138 */
139RTDECL(int) RTEnvGetEx(RTENV Env, const char *pszVar, char *pszValue, size_t cbValue, size_t *pcchActual);
140
141/**
142 * Puts an variable=value string into the environment (putenv).
143 *
144 * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
145 *
146 * @param pszVarEqualValue The variable '=' value string. If the value and '=' is
147 * omitted, the variable is removed from the environment.
148 *
149 * @remark Don't assume the value is copied.
150 * @remark WARNING! The current implementation does not perform the appropriate
151 * codeset conversion. We'll figure this out when it becomes necessary.
152 */
153RTDECL(int) RTEnvPut(const char *pszVarEqualValue);
154
155/**
156 * Puts a copy of the passed in 'variable=value' string into the environment block.
157 *
158 * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
159 *
160 * @param Env Handle of the environment block.
161 * @param pszVarEqualValue The variable '=' value string. If the value and '=' is
162 * omitted, the variable is removed from the environment.
163 */
164RTDECL(int) RTEnvPutEx(RTENV Env, const char *pszVarEqualValue);
165
166/**
167 * Sets an environment variable (setenv(,,1)).
168 *
169 * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
170 *
171 * @param pszVar The environment variable name.
172 * @param pszValue The environment variable value.
173 *
174 * @remark WARNING! The current implementation does not perform the appropriate
175 * codeset conversion. We'll figure this out when it becomes necessary.
176 */
177RTDECL(int) RTEnvSet(const char *pszVar, const char *pszValue);
178
179/**
180 * Sets an environment variable (setenv(,,1)).
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 * @param pszValue The environment variable value.
187 */
188RTDECL(int) RTEnvSetEx(RTENV Env, const char *pszVar, const char *pszValue);
189
190/**
191 * Removes an environment variable from the default environment block.
192 *
193 * @returns IPRT status code.
194 * @returns VINF_ENV_VAR_NOT_FOUND if the variable was not found.
195 *
196 * @param pszVar The environment variable name.
197 *
198 * @remark WARNING! The current implementation does not perform the appropriate
199 * codeset conversion. We'll figure this out when it becomes necessary.
200 */
201RTDECL(int) RTEnvUnset(const char *pszVar);
202
203/**
204 * Removes an environment variable from the specified environment block.
205 *
206 * @returns IPRT status code.
207 * @returns VINF_ENV_VAR_NOT_FOUND if the variable was not found.
208 *
209 * @param Env The environment handle.
210 * @param pszVar The environment variable name.
211 */
212RTDECL(int) RTEnvUnsetEx(RTENV Env, const char *pszVar);
213
214#endif /* IN_RING3 */
215
216/** @} */
217
218__END_DECLS
219
220#endif
221
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