env.h revision e4cda205c8155b43f1b07fbb328ea7d592a8d994
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * IPRT - Process Environment Strings.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * Copyright (C) 2006-2007 Oracle Corporation
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * available from http://www.virtualbox.org. This file is free software;
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * you can redistribute it and/or modify it under the terms of the GNU
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * General Public License (GPL) as published by the Free Software
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * The contents of this file may alternatively be used under the terms
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * of the Common Development and Distribution License Version 1.0
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * VirtualBox OSE distribution, in which case the provisions of the
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * CDDL are applicable instead of those of the GPL.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * You may elect to license modified versions of this file under the
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * terms and conditions of either the GPL or the CDDL or both.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync/** @defgroup grp_rt_env RTEnv - Process Environment Strings
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @ingroup grp_rt
a299266cddc1ae14d76d725a660bb278816bc151vboxsync/** Special handle that indicates the default process environment. */
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * Creates an empty environment block.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @param pEnv Where to store the handle of the new environment block.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * Creates an environment block and fill it with variables from the given
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * environment array.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @returns IPRT status code. Typical error is VERR_NO_MEMORY. Another
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * possible return code is VWRN_NO_TRANSLATION if EnvToClone is RTENV_DEFAULT
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * and there was no translation available for one environment variable. In
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * that case, the resulting environment will contain fewer elements than the
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * original environment.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @param pEnv Where to store the handle of the new environment block.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @param EnvToClone The environment to clone.
a299266cddc1ae14d76d725a660bb278816bc151vboxsyncRTDECL(int) RTEnvClone(PRTENV pEnv, RTENV EnvToClone);
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * Destroys an environment block.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @returns IPRT status code.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @param Env Environment block handle.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * Both RTENV_DEFAULT and NIL_RTENV are silently ignored.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * Get the execve/spawnve/main envp.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * All returned strings are in the current process' codepage.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * This array is only valid until the next RTEnv call.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @returns Pointer to the raw array of environment variables.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @returns NULL if Env is NULL or invalid.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @param Env Environment block handle.
a299266cddc1ae14d76d725a660bb278816bc151vboxsyncRTDECL(char const * const *) RTEnvGetExecEnvP(RTENV Env);
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * Get a sorted, UTF-16 environment block for CreateProcess.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @returns IPRT status code.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @param hEnv Environment block handle.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @param ppwszzBlock Where to return the environment block. This must be
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * freed by calling RTEnvFreeUtf16Block.
a299266cddc1ae14d76d725a660bb278816bc151vboxsyncRTDECL(int) RTEnvQueryUtf16Block(RTENV hEnv, PRTUTF16 *ppwszzBlock);
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * Frees an environment block returned by RTEnvGetUtf16Block().
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @param pwszzBlock What RTEnvGetUtf16Block returned. NULL is ignored.
a299266cddc1ae14d76d725a660bb278816bc151vboxsyncRTDECL(void) RTEnvFreeUtf16Block(PRTUTF16 pwszzBlock);
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * Checks if an environment variable exists in the default environment block.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @param pszVar The environment variable name.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @remark WARNING! The current implementation does not perform the appropriate
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * codeset conversion. We'll figure this out when it becomes necessary.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * Checks if an environment variable exists in a specific environment block.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @param Env The environment handle.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @param pszVar The environment variable name.
a299266cddc1ae14d76d725a660bb278816bc151vboxsyncRTDECL(bool) RTEnvExistEx(RTENV Env, const char *pszVar);
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * Gets an environment variable from the default environment block. (getenv).
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * The caller is responsible for ensuring that nobody changes the environment
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * while it's using the returned string pointer!
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @returns Pointer to read only string on success, NULL if the variable wasn't found.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @param pszVar The environment variable name.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @remark WARNING! The current implementation does not perform the appropriate
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * codeset conversion. We'll figure this out when it becomes necessary.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * Gets an environment variable in a specific environment block.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @returns IPRT status code.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @retval VERR_ENV_VAR_NOT_FOUND if the variable was not found.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @param Env The environment handle.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @param pszVar The environment variable name.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @param pszValue Where to put the buffer.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @param cbValue The size of the value buffer.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @param pcchActual Returns the actual value string length. Optional.
a299266cddc1ae14d76d725a660bb278816bc151vboxsyncRTDECL(int) RTEnvGetEx(RTENV Env, const char *pszVar, char *pszValue, size_t cbValue, size_t *pcchActual);
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * Puts an variable=value string into the environment (putenv).
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @param pszVarEqualValue The variable '=' value string. If the value and '=' is
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * omitted, the variable is removed from the environment.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @remark Don't assume the value is copied.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @remark WARNING! The current implementation does not perform the appropriate
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * codeset conversion. We'll figure this out when it becomes necessary.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * Puts a copy of the passed in 'variable=value' string into the environment block.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @param Env Handle of the environment block.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @param pszVarEqualValue The variable '=' value string. If the value and '=' is
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * omitted, the variable is removed from the environment.
a299266cddc1ae14d76d725a660bb278816bc151vboxsyncRTDECL(int) RTEnvPutEx(RTENV Env, const char *pszVarEqualValue);
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * Sets an environment variable (setenv(,,1)).
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @param pszVar The environment variable name.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @param pszValue The environment variable value.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @remark WARNING! The current implementation does not perform the appropriate
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * codeset conversion. We'll figure this out when it becomes necessary.
a299266cddc1ae14d76d725a660bb278816bc151vboxsyncRTDECL(int) RTEnvSet(const char *pszVar, const char *pszValue);
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * Sets an environment variable (setenv(,,1)).
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @param Env The environment handle.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @param pszVar The environment variable name.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @param pszValue The environment variable value.
da0b2d0ebcbeb635e76686254cc10c70faa37ee6vboxsyncRTDECL(int) RTEnvSetEx(RTENV Env, const char *pszVar, const char *pszValue);
da0b2d0ebcbeb635e76686254cc10c70faa37ee6vboxsync * Removes an environment variable from the default environment block.
da0b2d0ebcbeb635e76686254cc10c70faa37ee6vboxsync * @returns IPRT status code.
da0b2d0ebcbeb635e76686254cc10c70faa37ee6vboxsync * @returns VINF_ENV_VAR_NOT_FOUND if the variable was not found.
da0b2d0ebcbeb635e76686254cc10c70faa37ee6vboxsync * @param pszVar The environment variable name.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @remark WARNING! The current implementation does not perform the appropriate
da0b2d0ebcbeb635e76686254cc10c70faa37ee6vboxsync * codeset conversion. We'll figure this out when it becomes necessary.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * Removes an environment variable from the specified environment block.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @returns IPRT status code.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @returns VINF_ENV_VAR_NOT_FOUND if the variable was not found.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @param Env The environment handle.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @param pszVar The environment variable name.
a299266cddc1ae14d76d725a660bb278816bc151vboxsyncRTDECL(int) RTEnvUnsetEx(RTENV Env, const char *pszVar);
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * Duplicates the value of a environment variable if it exists.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @returns Pointer to a string containing the value, free it using RTStrFree.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * NULL if the variable was not found or we're out of memory.
a299266cddc1ae14d76d725a660bb278816bc151vboxsync * @param Env The environment handle.
da0b2d0ebcbeb635e76686254cc10c70faa37ee6vboxsync * @param pszVar The environment variable name.
da0b2d0ebcbeb635e76686254cc10c70faa37ee6vboxsyncRTDECL(char *) RTEnvDupEx(RTENV Env, const char *pszVar);
a299266cddc1ae14d76d725a660bb278816bc151vboxsync#endif /* IN_RING3 */