env.h revision 65a755c25b49d32c914e2d569fcdfb766e1ee879
c97989161fbe75bc14cea477a5443bbf474dd3advboxsync * innotek Portable Runtime - Process Environment Strings.
c97989161fbe75bc14cea477a5443bbf474dd3advboxsync * Copyright (C) 2006-2007 innotek GmbH
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
c39e02bbf326184d8f70d4d6f4fbceb8ea5b6b97vboxsync * General Public License as published by the Free Software Foundation,
c39e02bbf326184d8f70d4d6f4fbceb8ea5b6b97vboxsync * in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
c39e02bbf326184d8f70d4d6f4fbceb8ea5b6b97vboxsync * distribution. VirtualBox OSE is distributed in the hope that it will
c39e02bbf326184d8f70d4d6f4fbceb8ea5b6b97vboxsync * be useful, but WITHOUT ANY WARRANTY of any kind.
c39e02bbf326184d8f70d4d6f4fbceb8ea5b6b97vboxsync * If you received this file as part of a commercial VirtualBox
c39e02bbf326184d8f70d4d6f4fbceb8ea5b6b97vboxsync * distribution, then only the terms of your commercial VirtualBox
c39e02bbf326184d8f70d4d6f4fbceb8ea5b6b97vboxsync * license agreement apply instead of the previous paragraph.
c39e02bbf326184d8f70d4d6f4fbceb8ea5b6b97vboxsync/** @defgroup grp_rt_env RTProc - Process Environment Strings
c39e02bbf326184d8f70d4d6f4fbceb8ea5b6b97vboxsync * @ingroup grp_rt
739c77783387df1b22501b27bd870869a865d20cvboxsync * Checks if an environment variable exists.
739c77783387df1b22501b27bd870869a865d20cvboxsync * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
739c77783387df1b22501b27bd870869a865d20cvboxsync * @param pszVar The environment variable name.
c39e02bbf326184d8f70d4d6f4fbceb8ea5b6b97vboxsync * Gets an environment variable (getenv).
c39e02bbf326184d8f70d4d6f4fbceb8ea5b6b97vboxsync * 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.
c39e02bbf326184d8f70d4d6f4fbceb8ea5b6b97vboxsync * Puts an variable=value string into the environment (putenv).
c39e02bbf326184d8f70d4d6f4fbceb8ea5b6b97vboxsync * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
c39e02bbf326184d8f70d4d6f4fbceb8ea5b6b97vboxsync * @param pszVarEqualValue The variable '=' value string. If the value and '=' is
c39e02bbf326184d8f70d4d6f4fbceb8ea5b6b97vboxsync * omitted, the variable is removed from the environment.
739c77783387df1b22501b27bd870869a865d20cvboxsync * Sets an environment variable (setenv(,,1)).
739c77783387df1b22501b27bd870869a865d20cvboxsync * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
739c77783387df1b22501b27bd870869a865d20cvboxsync * @param pszVar The environment variable name.
739c77783387df1b22501b27bd870869a865d20cvboxsync * @param pszValue The environment variable value.
739c77783387df1b22501b27bd870869a865d20cvboxsyncRTDECL(int) RTEnvSet(const char *pszVar, const char *pszValue);
c39e02bbf326184d8f70d4d6f4fbceb8ea5b6b97vboxsync/** @todo Add the missing environment APIs: safe, printf like, and various modifications. */
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * Creates an empty environment block.
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * @param pEnv Where to store the handle of the environment block.
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * Destroys an environment block.
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * @returns IPRT status code.
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * @param Env Handle of the environment block.
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * Creates an environment block and fill it with variables from the given
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * environment array.
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * @param pEnv Where to store the handle of the environment block.
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * @param apszEnv Pointer to the NULL-terminated array of environment
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * variables. If NULL, the current process' environment
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * will be cloned.
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsyncRTDECL(int) RTEnvClone(PRTENV pEnv, char const *const *apszEnv);
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync/** @todo later */
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsyncRTDECL(int) RTEnvCloneEx(PRTENV pEnv, const RTENV Env);
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsyncRTDECL(int) RTEnvExistEx(RTENV Env, const char *pszVar);
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsyncRTDECL(int) RTEnvSetEx(RTENV Env, const char *pszVar, const char *pszValue);
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsyncRTDECL(int) RTEnvGetEx(RTENV Env, const char *pszVar, const char **ppszValue);
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsyncRTDECL(int) RTEnvCountEx(RTENV Env, size_t *cbCount);
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * Puts a 'variable=value' string into the environment.
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * The supplied string must be in the current process' codepage.
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * This function makes a copy of the supplied string.
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * @returns IPRT status code. Typical error is VERR_NO_MEMORY.
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * @param Env Handle of the environment block.
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * @param pszVarEqualValue The variable '=' value string. If the value and '=' is
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * omitted, the variable is removed from the environment.
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsyncRTDECL(int) RTEnvPutEx(RTENV Env, const char *pszVarEqualValue);
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * Returns a raw pointer to the array of environment variables of the given
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * environment block where every variable is a string in format
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * 'variable=value'.
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * All returned strings are in the current process' codepage.
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * @returns Pointer to the raw array of environment variables.
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * @returns NULL if Env is NULL or invalid.
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * @param Env Handle of the environment block.
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsyncRTDECL(char const *const *) RTEnvGetArray(RTENV Env);
c39e02bbf326184d8f70d4d6f4fbceb8ea5b6b97vboxsync#endif /* IN_RING3 */