5b281ba489ca18f0380d7efc7a5108b606cce449vboxsync * IPRT - Process Environment Strings.
c58f1213e628a545081c70e26c6b67a841cff880vboxsync * Copyright (C) 2006-2012 Oracle Corporation
c39e02bbf326184d8f70d4d6f4fbceb8ea5b6b97vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
c39e02bbf326184d8f70d4d6f4fbceb8ea5b6b97vboxsync * available from http://www.virtualbox.org. This file is free software;
c39e02bbf326184d8f70d4d6f4fbceb8ea5b6b97vboxsync * you can redistribute it and/or modify it under the terms of the GNU
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * General Public License (GPL) as published by the Free Software
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * The contents of this file may alternatively be used under the terms
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * of the Common Development and Distribution License Version 1.0
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * VirtualBox OSE distribution, in which case the provisions of the
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * CDDL are applicable instead of those of the GPL.
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * You may elect to license modified versions of this file under the
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * terms and conditions of either the GPL or the CDDL or both.
37314887c41636f91707b9ba0beaeb09136614c3vboxsync/** @defgroup grp_rt_env RTEnv - Process Environment Strings
c39e02bbf326184d8f70d4d6f4fbceb8ea5b6b97vboxsync * @ingroup grp_rt
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync/** Special handle that indicates the default process environment. */
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Creates an empty environment block.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param pEnv Where to store the handle of the new environment block.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Creates an environment block and fill it with variables from the given
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * environment array.
3d5d761b58f80f44f4e751bbc61caf2de4d7007cvboxsync * @returns IPRT status code.
3d5d761b58f80f44f4e751bbc61caf2de4d7007cvboxsync * @retval VWRN_ENV_NOT_FULLY_TRANSLATED may be returned when passing
3d5d761b58f80f44f4e751bbc61caf2de4d7007cvboxsync * RTENV_DEFAULT and one or more of the environment variables have
3d5d761b58f80f44f4e751bbc61caf2de4d7007cvboxsync * codeset incompatibilities. The problematic variables will be
3d5d761b58f80f44f4e751bbc61caf2de4d7007cvboxsync * ignored and not included in the clone, thus the clone will have
3d5d761b58f80f44f4e751bbc61caf2de4d7007cvboxsync * fewer variables.
3d5d761b58f80f44f4e751bbc61caf2de4d7007cvboxsync * @retval VERR_NO_MEMORY
3d5d761b58f80f44f4e751bbc61caf2de4d7007cvboxsync * @retval VERR_NO_STR_MEMORY
3d5d761b58f80f44f4e751bbc61caf2de4d7007cvboxsync * @retval VERR_INVALID_HANDLE
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param pEnv Where to store the handle of the new environment block.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param EnvToClone The environment to clone.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsyncRTDECL(int) RTEnvClone(PRTENV pEnv, RTENV EnvToClone);
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Destroys an environment block.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @returns IPRT status code.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param Env Environment block handle.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Both RTENV_DEFAULT and NIL_RTENV are silently ignored.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Get the execve/spawnve/main envp.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * All returned strings are in the current process' codepage.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * This array is only valid until the next RTEnv call.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @returns Pointer to the raw array of environment variables.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @returns NULL if Env is NULL or invalid.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param Env Environment block handle.
dbc6ecd6a6e372b8dcdf31d68bdab2d5b5e604d2vboxsync * @todo This needs to change to return a copy of the env vars like
dbc6ecd6a6e372b8dcdf31d68bdab2d5b5e604d2vboxsync * RTEnvQueryUtf16Block does!
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsyncRTDECL(char const * const *) RTEnvGetExecEnvP(RTENV Env);
98ac5f06a60dbc35241635f0d146c3d4ff55c727vboxsync * Get a sorted, UTF-16 environment block for CreateProcess.
98ac5f06a60dbc35241635f0d146c3d4ff55c727vboxsync * @returns IPRT status code.
98ac5f06a60dbc35241635f0d146c3d4ff55c727vboxsync * @param hEnv Environment block handle.
98ac5f06a60dbc35241635f0d146c3d4ff55c727vboxsync * @param ppwszzBlock Where to return the environment block. This must be
98ac5f06a60dbc35241635f0d146c3d4ff55c727vboxsync * freed by calling RTEnvFreeUtf16Block.
98ac5f06a60dbc35241635f0d146c3d4ff55c727vboxsyncRTDECL(int) RTEnvQueryUtf16Block(RTENV hEnv, PRTUTF16 *ppwszzBlock);
98ac5f06a60dbc35241635f0d146c3d4ff55c727vboxsync * Frees an environment block returned by RTEnvGetUtf16Block().
98ac5f06a60dbc35241635f0d146c3d4ff55c727vboxsync * @param pwszzBlock What RTEnvGetUtf16Block returned. NULL is ignored.
98ac5f06a60dbc35241635f0d146c3d4ff55c727vboxsyncRTDECL(void) RTEnvFreeUtf16Block(PRTUTF16 pwszzBlock);
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Checks if an environment variable exists in the default environment block.
739c77783387df1b22501b27bd870869a865d20cvboxsync * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
739c77783387df1b22501b27bd870869a865d20cvboxsync * @param pszVar The environment variable name.
51f9db691d747d579ebd9047e86aab26105b6bc3vboxsync * @remark WARNING! The current implementation does not perform the appropriate
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * codeset conversion. We'll figure this out when it becomes necessary.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Checks if an environment variable exists in a specific environment block.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param Env The environment handle.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param pszVar The environment variable name.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsyncRTDECL(bool) RTEnvExistEx(RTENV Env, const char *pszVar);
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Gets an environment variable from the default environment block. (getenv).
51f9db691d747d579ebd9047e86aab26105b6bc3vboxsync * The caller is responsible for ensuring that nobody changes the environment
c39e02bbf326184d8f70d4d6f4fbceb8ea5b6b97vboxsync * while it's using the returned string pointer!
c39e02bbf326184d8f70d4d6f4fbceb8ea5b6b97vboxsync * @returns Pointer to read only string on success, NULL if the variable wasn't found.
c39e02bbf326184d8f70d4d6f4fbceb8ea5b6b97vboxsync * @param pszVar The environment variable name.
51f9db691d747d579ebd9047e86aab26105b6bc3vboxsync * @remark WARNING! The current implementation does not perform the appropriate
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * codeset conversion. We'll figure this out when it becomes necessary.
dbc6ecd6a6e372b8dcdf31d68bdab2d5b5e604d2vboxsyncRTDECL(const char *) RTEnvGetBad(const char *pszVar);
dbc6ecd6a6e372b8dcdf31d68bdab2d5b5e604d2vboxsyncRTDECL(int) RTEnvGetUtf8(const char *pszVar, char *pszValue, size_t cbValue, size_t *pcchActual);
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Gets an environment variable in a specific environment block.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @returns IPRT status code.
831b4c533723665e3a004ca13c9f413f4221ffbbvboxsync * @retval VERR_ENV_VAR_NOT_FOUND if the variable was not found.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param Env The environment handle.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param pszVar The environment variable name.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param pszValue Where to put the buffer.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param cbValue The size of the value buffer.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param pcchActual Returns the actual value string length. Optional.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsyncRTDECL(int) RTEnvGetEx(RTENV Env, const char *pszVar, char *pszValue, size_t cbValue, size_t *pcchActual);
c39e02bbf326184d8f70d4d6f4fbceb8ea5b6b97vboxsync * Puts an variable=value string into the environment (putenv).
c39e02bbf326184d8f70d4d6f4fbceb8ea5b6b97vboxsync * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
51f9db691d747d579ebd9047e86aab26105b6bc3vboxsync * @param pszVarEqualValue The variable '=' value string. If the value and '=' is
c39e02bbf326184d8f70d4d6f4fbceb8ea5b6b97vboxsync * omitted, the variable is removed from the environment.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @remark Don't assume the value is copied.
51f9db691d747d579ebd9047e86aab26105b6bc3vboxsync * @remark WARNING! The current implementation does not perform the appropriate
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * codeset conversion. We'll figure this out when it becomes necessary.
dbc6ecd6a6e372b8dcdf31d68bdab2d5b5e604d2vboxsyncRTDECL(int) RTEnvPutBad(const char *pszVarEqualValue);
dbc6ecd6a6e372b8dcdf31d68bdab2d5b5e604d2vboxsyncRTDECL(int) RTEnvPutUtf8(const char *pszVarEqualValue);
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Puts a copy of the passed in 'variable=value' string into the environment block.
739c77783387df1b22501b27bd870869a865d20cvboxsync * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param Env Handle of the environment block.
51f9db691d747d579ebd9047e86aab26105b6bc3vboxsync * @param pszVarEqualValue The variable '=' value string. If the value and '=' is
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * omitted, the variable is removed from the environment.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsyncRTDECL(int) RTEnvPutEx(RTENV Env, const char *pszVarEqualValue);
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Sets an environment variable (setenv(,,1)).
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param pszVar The environment variable name.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param pszValue The environment variable value.
51f9db691d747d579ebd9047e86aab26105b6bc3vboxsync * @remark WARNING! The current implementation does not perform the appropriate
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * codeset conversion. We'll figure this out when it becomes necessary.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsyncRTDECL(int) RTEnvSet(const char *pszVar, const char *pszValue);
dbc6ecd6a6e372b8dcdf31d68bdab2d5b5e604d2vboxsyncRTDECL(int) RTEnvSetBad(const char *pszVar, const char *pszValue);
dbc6ecd6a6e372b8dcdf31d68bdab2d5b5e604d2vboxsyncRTDECL(int) RTEnvSetUtf8(const char *pszVar, const char *pszValue);
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Sets an environment variable (setenv(,,1)).
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param Env The environment handle.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param pszVar The environment variable name.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param pszValue The environment variable value.
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsyncRTDECL(int) RTEnvSetEx(RTENV Env, const char *pszVar, const char *pszValue);
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Removes an environment variable from the default environment block.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @returns IPRT status code.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @returns VINF_ENV_VAR_NOT_FOUND if the variable was not found.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param pszVar The environment variable name.
51f9db691d747d579ebd9047e86aab26105b6bc3vboxsync * @remark WARNING! The current implementation does not perform the appropriate
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * codeset conversion. We'll figure this out when it becomes necessary.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Removes an environment variable from the specified environment block.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @returns IPRT status code.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @returns VINF_ENV_VAR_NOT_FOUND if the variable was not found.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param Env The environment handle.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param pszVar The environment variable name.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsyncRTDECL(int) RTEnvUnsetEx(RTENV Env, const char *pszVar);
831b4c533723665e3a004ca13c9f413f4221ffbbvboxsync * Duplicates the value of a environment variable if it exists.
831b4c533723665e3a004ca13c9f413f4221ffbbvboxsync * @returns Pointer to a string containing the value, free it using RTStrFree.
831b4c533723665e3a004ca13c9f413f4221ffbbvboxsync * NULL if the variable was not found or we're out of memory.
831b4c533723665e3a004ca13c9f413f4221ffbbvboxsync * @param Env The environment handle.
831b4c533723665e3a004ca13c9f413f4221ffbbvboxsync * @param pszVar The environment variable name.
831b4c533723665e3a004ca13c9f413f4221ffbbvboxsyncRTDECL(char *) RTEnvDupEx(RTENV Env, const char *pszVar);
7757e065b2ef522ec99a434fbeeae8665a36543avboxsync * Counts the variables in the environment.
7757e065b2ef522ec99a434fbeeae8665a36543avboxsync * @returns Number of variables in the environment. UINT32_MAX on error.
7757e065b2ef522ec99a434fbeeae8665a36543avboxsync * @param hEnv The environment handle.
7757e065b2ef522ec99a434fbeeae8665a36543avboxsync * RTENV_DEFAULT is currently not accepted.
7757e065b2ef522ec99a434fbeeae8665a36543avboxsync * Queries an environment variable by it's index.
7757e065b2ef522ec99a434fbeeae8665a36543avboxsync * This can be used together with RTEnvCount to enumerate the environment block.
7757e065b2ef522ec99a434fbeeae8665a36543avboxsync * @returns IPRT status code.
7757e065b2ef522ec99a434fbeeae8665a36543avboxsync * @retval VERR_ENV_VAR_NOT_FOUND if the index is out of bounds, output buffers
7757e065b2ef522ec99a434fbeeae8665a36543avboxsync * untouched.
7757e065b2ef522ec99a434fbeeae8665a36543avboxsync * @retval VERR_BUFFER_OVERFLOW if one of the buffers are too small. We'll
7757e065b2ef522ec99a434fbeeae8665a36543avboxsync * fill it with as much we can in RTStrCopy fashion.
7757e065b2ef522ec99a434fbeeae8665a36543avboxsync * @param hEnv The environment handle.
7757e065b2ef522ec99a434fbeeae8665a36543avboxsync * RTENV_DEFAULT is currently not accepted.
7757e065b2ef522ec99a434fbeeae8665a36543avboxsync * @param iVar The variable index.
7757e065b2ef522ec99a434fbeeae8665a36543avboxsync * @param pszVar Variable name buffer.
7757e065b2ef522ec99a434fbeeae8665a36543avboxsync * @param cbVar The size of the variable name buffer.
7757e065b2ef522ec99a434fbeeae8665a36543avboxsync * @param pszValue Value buffer.
7757e065b2ef522ec99a434fbeeae8665a36543avboxsync * @param cbValue The size of the value buffer.
7757e065b2ef522ec99a434fbeeae8665a36543avboxsyncRTDECL(uint32_t) RTEnvGetByIndexEx(RTENV hEnv, uint32_t iVar, char *pszVar, size_t cbVar, char *pszValue, size_t cbValue);
c39e02bbf326184d8f70d4d6f4fbceb8ea5b6b97vboxsync#endif /* IN_RING3 */