env.h revision 65a755c25b49d32c914e2d569fcdfb766e1ee879
/** @file
* innotek Portable Runtime - Process Environment Strings.
*/
/*
* Copyright (C) 2006-2007 innotek GmbH
*
* This file is part of VirtualBox Open Source Edition (OSE), as
* available from http://www.virtualbox.org. This file is free software;
* General Public License as published by the Free Software Foundation,
* in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
* distribution. VirtualBox OSE is distributed in the hope that it will
* be useful, but WITHOUT ANY WARRANTY of any kind.
*
* If you received this file as part of a commercial VirtualBox
* distribution, then only the terms of your commercial VirtualBox
* license agreement apply instead of the previous paragraph.
*/
#ifndef ___iprt_env_h
#define ___iprt_env_h
/** @defgroup grp_rt_env RTProc - Process Environment Strings
* @ingroup grp_rt
* @{
*/
#ifdef IN_RING3
/**
* Checks if an environment variable exists.
*
* @returns IPRT status code. Typical error is VERR_NO_MEMORY.
*
* @param pszVar The environment variable name.
*/
/**
* Gets an environment variable (getenv).
*
* The caller is responsible for ensuring that nobody changes the environment
* while it's using the returned string pointer!
*
* @returns Pointer to read only string on success, NULL if the variable wasn't found.
*
* @param pszVar The environment variable name.
*/
/**
* Puts an variable=value string into the environment (putenv).
*
* @returns IPRT status code. Typical error is VERR_NO_MEMORY.
*
* @param pszVarEqualValue The variable '=' value string. If the value and '=' is
* omitted, the variable is removed from the environment.
*/
/**
* Sets an environment variable (setenv(,,1)).
*
* @returns IPRT status code. Typical error is VERR_NO_MEMORY.
*
* @param pszVar The environment variable name.
* @param pszValue The environment variable value.
*/
/** @todo Add the missing environment APIs: safe, printf like, and various modifications. */
/**
* Creates an empty environment block.
*
* @returns IPRT status code. Typical error is VERR_NO_MEMORY.
*
* @param pEnv Where to store the handle of the environment block.
*/
/**
* Destroys an environment block.
*
* @returns IPRT status code.
*
* @param Env Handle of the environment block.
*/
/**
* Creates an environment block and fill it with variables from the given
* environment array.
*
* @returns IPRT status code. Typical error is VERR_NO_MEMORY.
*
* @param pEnv Where to store the handle of the environment block.
* @param apszEnv Pointer to the NULL-terminated array of environment
* variables. If NULL, the current process' environment
* will be cloned.
*/
/** @todo later */
/*
RTDECL(int) RTEnvCloneEx(PRTENV pEnv, const RTENV Env);
RTDECL(int) RTEnvExistEx(RTENV Env, const char *pszVar);
RTDECL(int) RTEnvSetEx(RTENV Env, const char *pszVar, const char *pszValue);
RTDECL(int) RTEnvGetEx(RTENV Env, const char *pszVar, const char **ppszValue);
RTDECL(int) RTEnvCountEx(RTENV Env, size_t *cbCount);
*/
/**
* Puts a 'variable=value' string into the environment.
*
* The supplied string must be in the current process' codepage.
* This function makes a copy of the supplied string.
*
* @returns IPRT status code. Typical error is VERR_NO_MEMORY.
*
* @param Env Handle of the environment block.
* @param pszVarEqualValue The variable '=' value string. If the value and '=' is
* omitted, the variable is removed from the environment.
*/
/**
* Returns a raw pointer to the array of environment variables of the given
* environment block where every variable is a string in format
* 'variable=value'.
*
* All returned strings are in the current process' codepage.
*
* @returns Pointer to the raw array of environment variables.
* @returns NULL if Env is NULL or invalid.
*
* @param Env Handle of the environment block.
*/
#endif /* IN_RING3 */
/** @} */
#endif