env.h revision a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fc
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * innotek Portable Runtime - Process Environment Strings.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * Copyright (C) 2006-2007 innotek GmbH
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * available from http://www.virtualbox.org. This file is free software;
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * you can redistribute it and/or modify it under the terms of the GNU
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * General Public License (GPL) as published by the Free Software
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * The contents of this file may alternatively be used under the terms
0d12c7f9423f2745f8e282523d0930f91bff03b3vboxsync * of the Common Development and Distribution License Version 1.0
0d12c7f9423f2745f8e282523d0930f91bff03b3vboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
0d12c7f9423f2745f8e282523d0930f91bff03b3vboxsync * VirtualBox OSE distribution, in which case the provisions of the
0d12c7f9423f2745f8e282523d0930f91bff03b3vboxsync * CDDL are applicable instead of those of the GPL.
0d12c7f9423f2745f8e282523d0930f91bff03b3vboxsync * You may elect to license modified versions of this file under the
0d12c7f9423f2745f8e282523d0930f91bff03b3vboxsync * terms and conditions of either the GPL or the CDDL or both.
590bfe12ce22cd3716448fbb9f4dc51664bfe5e2vboxsync/** @defgroup grp_rt_env RTProc - Process Environment Strings
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @ingroup grp_rt
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync/** Special handle that indicates the default process environment. */
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * Creates an empty environment block.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @param pEnv Where to store the handle of the new environment block.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * Creates an environment block and fill it with variables from the given
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * environment array.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
c2046db2cc346cc299f0cd9b2d1e160179159cfcvboxsync * @param pEnv Where to store the handle of the new environment block.
c2046db2cc346cc299f0cd9b2d1e160179159cfcvboxsync * @param EnvToClone The environment to clone.
c2046db2cc346cc299f0cd9b2d1e160179159cfcvboxsyncRTDECL(int) RTEnvClone(PRTENV pEnv, RTENV EnvToClone);
b7a07b07543924f45c1fffd2f90de582038b8ba6vboxsync * Destroys an environment block.
2d8870843ff566fee9bd3a6a5942414254106479vboxsync * @returns IPRT status code.
2d8870843ff566fee9bd3a6a5942414254106479vboxsync * @param Env Environment block handle.
2d8870843ff566fee9bd3a6a5942414254106479vboxsync * Both RTENV_DEFAULT and NIL_RTENV are silently ignored.
2d8870843ff566fee9bd3a6a5942414254106479vboxsync * Get the execve/spawnve/main envp.
2d8870843ff566fee9bd3a6a5942414254106479vboxsync * All returned strings are in the current process' codepage.
044af0d1e6474076366759db86f101778c5f20ccvboxsync * This array is only valid until the next RTEnv call.
044af0d1e6474076366759db86f101778c5f20ccvboxsync * @returns Pointer to the raw array of environment variables.
044af0d1e6474076366759db86f101778c5f20ccvboxsync * @returns NULL if Env is NULL or invalid.
044af0d1e6474076366759db86f101778c5f20ccvboxsync * @param Env Environment block handle.
044af0d1e6474076366759db86f101778c5f20ccvboxsyncRTDECL(char const * const *) RTEnvGetExecEnvP(RTENV Env);
044af0d1e6474076366759db86f101778c5f20ccvboxsync * Checks if an environment variable exists in the default environment block.
044af0d1e6474076366759db86f101778c5f20ccvboxsync * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
044af0d1e6474076366759db86f101778c5f20ccvboxsync * @param pszVar The environment variable name.
044af0d1e6474076366759db86f101778c5f20ccvboxsync * @remark WARNING! The current implementation does not perform the appropriate
044af0d1e6474076366759db86f101778c5f20ccvboxsync * codeset conversion. We'll figure this out when it becomes necessary.
044af0d1e6474076366759db86f101778c5f20ccvboxsync * Checks if an environment variable exists in a specific environment block.
044af0d1e6474076366759db86f101778c5f20ccvboxsync * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
044af0d1e6474076366759db86f101778c5f20ccvboxsync * @param Env The environment handle.
044af0d1e6474076366759db86f101778c5f20ccvboxsync * @param pszVar The environment variable name.
044af0d1e6474076366759db86f101778c5f20ccvboxsyncRTDECL(bool) RTEnvExistEx(RTENV Env, const char *pszVar);
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * Gets an environment variable from the default environment block. (getenv).
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * The caller is responsible for ensuring that nobody changes the environment
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * while it's using the returned string pointer!
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @returns Pointer to read only string on success, NULL if the variable wasn't found.
ca3da10d05961c339b5180fbd40a54587d6bad35vboxsync * @param pszVar The environment variable name.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @remark WARNING! The current implementation does not perform the appropriate
044af0d1e6474076366759db86f101778c5f20ccvboxsync * codeset conversion. We'll figure this out when it becomes necessary.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * Gets an environment variable in a specific environment block.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @returns IPRT status code.
044af0d1e6474076366759db86f101778c5f20ccvboxsync * @param Env The environment handle.
044af0d1e6474076366759db86f101778c5f20ccvboxsync * @param pszVar The environment variable name.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @param pszValue Where to put the buffer.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @param cbValue The size of the value buffer.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @param pcchActual Returns the actual value string length. Optional.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsyncRTDECL(int) RTEnvGetEx(RTENV Env, const char *pszVar, char *pszValue, size_t cbValue, size_t *pcchActual);
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * Puts an variable=value string into the environment (putenv).
ca3da10d05961c339b5180fbd40a54587d6bad35vboxsync * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
ca3da10d05961c339b5180fbd40a54587d6bad35vboxsync * @param pszVarEqualValue The variable '=' value string. If the value and '=' is
ca3da10d05961c339b5180fbd40a54587d6bad35vboxsync * omitted, the variable is removed from the environment.
ca3da10d05961c339b5180fbd40a54587d6bad35vboxsync * @remark Don't assume the value is copied.
ca3da10d05961c339b5180fbd40a54587d6bad35vboxsync * @remark WARNING! The current implementation does not perform the appropriate
ca3da10d05961c339b5180fbd40a54587d6bad35vboxsync * codeset conversion. We'll figure this out when it becomes necessary.
ca3da10d05961c339b5180fbd40a54587d6bad35vboxsync * Puts a copy of the passed in 'variable=value' string into the environment block.
ca3da10d05961c339b5180fbd40a54587d6bad35vboxsync * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
ca3da10d05961c339b5180fbd40a54587d6bad35vboxsync * @param Env Handle of the environment block.
ca3da10d05961c339b5180fbd40a54587d6bad35vboxsync * @param pszVarEqualValue The variable '=' value string. If the value and '=' is
a1df400bbe9d64aad400442e56eb637019300a5evboxsync * omitted, the variable is removed from the environment.
a1df400bbe9d64aad400442e56eb637019300a5evboxsyncRTDECL(int) RTEnvPutEx(RTENV Env, const char *pszVarEqualValue);
ca3da10d05961c339b5180fbd40a54587d6bad35vboxsync * Sets an environment variable (setenv(,,1)).
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @param pszVar The environment variable name.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @param pszValue The environment variable value.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @remark WARNING! The current implementation does not perform the appropriate
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * codeset conversion. We'll figure this out when it becomes necessary.
ca3da10d05961c339b5180fbd40a54587d6bad35vboxsyncRTDECL(int) RTEnvSet(const char *pszVar, const char *pszValue);
ca3da10d05961c339b5180fbd40a54587d6bad35vboxsync * Sets an environment variable (setenv(,,1)).
ca3da10d05961c339b5180fbd40a54587d6bad35vboxsync * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @param Env The environment handle.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @param pszVar The environment variable name.
044af0d1e6474076366759db86f101778c5f20ccvboxsync * @param pszValue The environment variable value.
044af0d1e6474076366759db86f101778c5f20ccvboxsyncRTDECL(int) RTEnvSetEx(RTENV Env, const char *pszVar, const char *pszValue);
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * Removes an environment variable from the default environment block.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @returns IPRT status code.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @returns VINF_ENV_VAR_NOT_FOUND if the variable was not found.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @param pszVar The environment variable name.
7d80dfbe5d66fc4c6de6fe109ce96a081496dcd4vboxsync * @remark WARNING! The current implementation does not perform the appropriate
7d80dfbe5d66fc4c6de6fe109ce96a081496dcd4vboxsync * codeset conversion. We'll figure this out when it becomes necessary.
7d80dfbe5d66fc4c6de6fe109ce96a081496dcd4vboxsync * Removes an environment variable from the specified environment block.
7d80dfbe5d66fc4c6de6fe109ce96a081496dcd4vboxsync * @returns IPRT status code.
7d80dfbe5d66fc4c6de6fe109ce96a081496dcd4vboxsync * @returns VINF_ENV_VAR_NOT_FOUND if the variable was not found.
7d80dfbe5d66fc4c6de6fe109ce96a081496dcd4vboxsync * @param Env The environment handle.
7d80dfbe5d66fc4c6de6fe109ce96a081496dcd4vboxsync * @param pszVar The environment variable name.
7d80dfbe5d66fc4c6de6fe109ce96a081496dcd4vboxsyncRTDECL(int) RTEnvUnsetEx(RTENV Env, const char *pszVar);
7d80dfbe5d66fc4c6de6fe109ce96a081496dcd4vboxsync#endif /* IN_RING3 */