env.h File Reference

Prototypes for functions for setting and getting environment variables. More...

#include <wchar.h>
#include "util.h"

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Defines
#define	ENV_LOCAL   1
	Flag for local (to the current block) variable.
#define	ENV_EXPORT   2
	Flag for exported (to commands) variable.
#define	ENV_UNEXPORT   16
	Flag for unexported variable.
#define	ENV_GLOBAL   4
	Flag for global variable.
#define	ENV_USER   8
	Flag for variable update request from the user.
#define	ENV_UNIVERSAL   32
	Flag for universal variable.
Enumerations
enum	{ ENV_PERM = 1, ENV_INVALID }
	Error code for trying to alter read-only variable.
Functions
void	env_init ()
	Initialize environment variable data.
void	env_destroy ()
	Destroy environment variable data.
int	env_set (const wchar_t *key, const wchar_t *val, int mode)
	Set the value of the environment variable whose name matches key to val.
wchar_t *	env_get (const wchar_t *key)
	Return the value of the variable with the specified name.
int	env_exist (const wchar_t *key, int mode)
	Returns 1 if the specified key exists.
int	env_remove (const wchar_t *key, int mode)
	Remove environemnt variable.
void	env_push (int new_scope)
	Push the variable stack.
void	env_pop ()
	Pop the variable stack.
char **	env_export_arr (int recalc)
	Returns an array containing all exported variables in a format suitable for execv.
void	env_get_names (array_list_t *l, int flags)
	Insert all variable names into l.
int	env_set_pwd ()
	Update the PWD variable directory.

---

Detailed Description

Prototypes for functions for setting and getting environment variables.

---

Define Documentation

#define ENV_USER   8

Flag for variable update request from the user.

All variable changes that are made directly by the user, such as those from the 'set' builtin must have this flag set.

Referenced by builtin_read(), builtin_set(), env_remove(), env_set(), and my_env_set().

---

Function Documentation

int env_exist	(	const wchar_t *	key,
		int	mode
	)

Returns 1 if the specified key exists.

This can't be reliably done using env_get, since env_get returns null for 0-element arrays

Parameters:

	key	The name of the variable to remove
	mode	the scope to search in. All scopes are searched if unset

References CHECK, env_node::env, ENV_GLOBAL, ENV_LOCAL, ENV_UNIVERSAL, env_universal_barrier(), hash_get(), env_node::new_scope, env_node::next, and proc_had_barrier.

Referenced by builtin_set().

wchar_t* env_get

(

const wchar_t *

key

)

Return the value of the variable with the specified name.

Returns 0 if the key does not exist. The returned string should not be modified or freed. The returned string is only guaranteed to be valid until the next call to env_get(), env_set(), env_push() or env_pop() takes place.

References ARRAY_SEP_STR, buffer::buff, CHECK, common_get_height(), common_get_width(), env_node::env, ENV_NULL, env_universal_barrier(), get_umask(), hash_get(), history_get(), env_node::new_scope, env_node::next, proc_get_last_status(), proc_had_barrier, reader_get_buffer(), sb_append, sb_clear(), sb_printf(), and var_entry::val.

Referenced by autoload_names(), builtin_cd(), builtin_read(), builtin_set(), calc_prompt_width(), complete_cmd(), complete_variable(), env_init(), env_set_defaults(), exec_subshell(), expand_tilde_internal(), expand_var(), handle_locale(), highlight_get_color(), input_init(), kill_add(), kill_check_x_buffer(), parse_job(), parse_util_load(), path_get_cdpath(), path_get_config(), path_get_path(), print_variables(), reader_write_title(), and setup_path().

void env_get_names	(	array_list_t *	l,
		int	flags
	)

Insert all variable names into l.

These are not copies of the strings and should not be freed after use.

References add_key_to_hash(), add_key_to_list(), add_to_hash(), al_destroy(), al_foreach2(), al_init(), al_push(), CHECK, env_node::env, ENV_EXPORT, ENV_GLOBAL, ENV_LOCAL, ENV_UNEXPORT, ENV_UNIVERSAL, get_names_show_exported, get_names_show_unexported, hash_destroy(), hash_foreach2(), hash_get_keys(), hash_init(), hash_wcs_cmp(), hash_wcs_func(), env_node::new_scope, and env_node::next.

Referenced by complete_variable(), and print_variables().

void env_pop

(

)

Pop the variable stack.

Used for implementing local variables for functions and for-loops.

References _, clear_hash_entry(), debug(), env_node::env, env_node::export, handle_locale(), has_changed, hash_destroy(), hash_foreach(), hash_get(), killme, local_scope_exports(), locale_variable, env_node::new_scope, env_node::next, and sanity_lose().

Referenced by builtin_else(), env_destroy(), and parser_push_block().

void env_push

(

int

new_scope

)

Push the variable stack.

Used for implementing local variables for functions and for-loops.

References env_node::env, env_node::export, has_changed, hash_init(), hash_wcs_cmp(), hash_wcs_func(), local_scope_exports(), env_node::new_scope, and env_node::next.

Referenced by builtin_else(), and parser_push_block().

int env_remove	(	const wchar_t *	key,
		int	mode
	)

Remove environemnt variable.

Parameters:

	key	The name of the variable to remove
	mode	should be ENV_USER if this is a remove request from the user, 0 otherwise. If this is a user request, read-only variables can not be removed. The mode may also specify the scope of the variable that should be erased.

Returns:

zero if the variable existed, and non-zero if the variable did not exist

References al_destroy(), al_init(), al_push(), event_t::arguments, CHECK, ENV_GLOBAL, ENV_LOCAL, ENV_UNIVERSAL, ENV_USER, event_fire(), EVENT_VARIABLE, event_t::function_name, handle_locale(), hash_get(), is_locale(), event_t::param1, try_remove(), event_t::type, and event_t::variable.

Referenced by builtin_set().

int env_set	(	const wchar_t *	key,
		const wchar_t *	val,
		int	mode
	)

Set the value of the environment variable whose name matches key to val.

Memory policy: All keys and values are copied, the parameters can and should be freed by the caller afterwards

Parameters:

	key	The key
	val	The value
	mode	The type of the variable. Can be any combination of ENV_GLOBAL, ENV_LOCAL, ENV_EXPORT and ENV_USER. If mode is zero, the current variable space is searched and the current mode is used. If no current variable with the same name is found, ENV_LOCAL is assumed.

Returns:

0 on suicess or an error code on failiure.

The current error codes are:

ENV_PERM, can only be returned when setting as a user, e.g. ENV_USER is set. This means that the user tried to change a read-only variable. ENV_INVALID, the variable name or mode was invalid

References al_destroy(), al_init(), al_push(), event_t::arguments, CHECK, contains, DIE_MEM, env_node::env, ENV_EXPORT, env_get_node(), ENV_GLOBAL, ENV_LOCAL, ENV_NULL, env_set(), ENV_UNEXPORT, ENV_UNIVERSAL, env_universal_barrier(), ENV_USER, event_fire(), EVENT_VARIABLE, env_node::export, var_entry::export, event_t::function_name, halloc(), halloc_free(), handle_locale(), has_changed, hash_get(), hash_put(), hash_remove(), is_locale(), env_node::new_scope, env_node::next, event_t::param1, proc_had_barrier, var_entry::size, event_t::type, var_entry::val, and event_t::variable.

Referenced by builtin_end(), builtin_fg(), builtin_for(), builtin_read(), env_init(), env_set(), env_set_defaults(), env_set_pwd(), main(), my_env_set(), parse_util_set_argv(), reader_interactive_init(), reader_run_command(), and setup_path().