Environment variables and system specific defaults. More...

#include "gate/gate_core_api.h"
#include "gate/gatetypes.h"
#include "gate/strings.h"
#include "gate/maps.h"

Macros
#define	GATE_ENV_DOCUMENTS 0x0001
#define	GATE_ENV_PICTURES 0x0002
#define	GATE_ENV_MUSIC 0x0004
#define	GATE_ENV_VIDEOS 0x0008
#define	GATE_ENV_DESKTOP 0x0010
#define	GATE_ENV_APPDATA 0x1000

Typedefs
typedef gate_bool_t(*	gate_env_enum_callback_t) (char const varname, char const varvalue, void *userparam)
	Callback type for gate_env_list_vars()

Functions
GATE_CORE_API gate_result_t	gate_env_list_vars (gate_env_enum_callback_t callback, void *userparam)
	Enumerates all environment variables and invokes a callback function for each variable.
GATE_CORE_API gate_result_t	gate_env_get_var (gate_string_t const varname, gate_string_t varvalue)
	Retrieves the value of a specific environment variable.
GATE_CORE_API gate_result_t	gate_env_get_var_str (char const varname, gate_size_t varname_length, char value, gate_size_t value_capacity, gate_size_t *value_used)
	Retrieves the value of a specific environment variable.
GATE_CORE_API gate_result_t	gate_env_get_var_map (gate_map_t *strmap)
	Creates a gate_map_t<gate_string_t, gate_string_t> with all environment variables.
GATE_CORE_API gate_result_t	gate_env_get_workpath (gate_string_t *workpath)
	Retrieves the current working directory of the process.
GATE_CORE_API gate_result_t	gate_env_set_workpath (gate_string_t const *workpath)
	Sets the current working directory of the process.
GATE_CORE_API gate_result_t	gate_env_temp_rootpath (gate_string_t *temppath)
	Returns the filesystem path of the systems TEMP directory.
GATE_CORE_API gate_result_t	gate_env_home_rootpath (gate_string_t *homepath)
	Returns the filesystem path of the systems HOME directory.
GATE_CORE_API gate_result_t	gate_env_app_rootpath (gate_string_t *apppath)
	Returns the filesystem path of the directory where the process executable is located.
GATE_CORE_API gate_result_t	gate_env_app_executable_str (char buffer, gate_size_t buffer_len)
	Fills a buffer with the filesystem path of the process' executable.
GATE_CORE_API gate_result_t	gate_env_app_executable (gate_string_t *executablepath)
	Returns the filesystem path of the process' executable as a string.
GATE_CORE_API gate_result_t	gate_env_app_executable_name_str (char buffer, gate_size_t buffer_len)
	Fills a buffer with the filename of the process' executable.
GATE_CORE_API gate_result_t	gate_env_app_executable_name (gate_string_t *executablename)
	Returns the filename of the process' executable as a string.
GATE_CORE_API gate_result_t	gate_env_app_configpath (gate_string_t const appname, gate_bool_t global_config, gate_string_t appdatapath)
	Returns the filesystem path where an app can store configuration files.
GATE_CORE_API gate_result_t	gate_env_data_path (gate_uint32_t dataid, gate_string_t *datapath)
	Returns a filesystem folder of a specific data directory of the user account running the process.
GATE_CORE_API gate_result_t	gate_env_host_name (gate_string_t *hostname)
	Returns the name of the hosting machine running the process.
GATE_CORE_API gate_result_t	gate_env_user_name (gate_string_t *username)
	Returns the name of the user account running the process.
GATE_CORE_API gate_result_t	gate_env_shell_path (gate_string_t *shellpath)
	Returns the path to the default command line shell program.

Detailed Description

Environment variables and system specific defaults.

Macro Definition Documentation

◆ GATE_ENV_DOCUMENTS

#define GATE_ENV_DOCUMENTS 0x0001

data path ID for user's "documents" folder

◆ GATE_ENV_PICTURES

#define GATE_ENV_PICTURES 0x0002

data path ID for user's "pictures" folder

◆ GATE_ENV_MUSIC

#define GATE_ENV_MUSIC 0x0004

data path ID for user's "music" folder

◆ GATE_ENV_VIDEOS

#define GATE_ENV_VIDEOS 0x0008

data path ID for user's "videos" folder

◆ GATE_ENV_DESKTOP

#define GATE_ENV_DESKTOP 0x0010

data path ID for user's "desktop files" folder

◆ GATE_ENV_APPDATA

#define GATE_ENV_APPDATA 0x1000

data path ID for user's "application data" root folder

Function Documentation

◆ gate_env_list_vars()

GATE_CORE_API gate_result_t gate_env_list_vars	(	gate_env_enum_callback_t	callback,
		void *	userparam )

Enumerates all environment variables and invokes a callback function for each variable.

Parameters

[in]	callback	Callback function to be called with each environment variable
[in]	userparam	User defined parameter that is used on each invocation of `callback`

Returns: GATE_RESULT_* result code

◆ gate_env_get_var()

GATE_CORE_API gate_result_t gate_env_get_var	(	gate_string_t const *	varname,
		gate_string_t *	varvalue )

Retrieves the value of a specific environment variable.

Parameters

[in]	varname	Variable name to be accessed
[out]	varvalue	Pointer to string to be initialized with value of retrieved environment variable

Returns: GATE_RESULT_* result code

◆ gate_env_get_var_str()

GATE_CORE_API gate_result_t gate_env_get_var_str	(	char const *	varname,
		gate_size_t	varname_length,
		char *	value,
		gate_size_t	value_capacity,
		gate_size_t *	value_used )

Retrieves the value of a specific environment variable.

Parameters

[in]	varname	Variable name to be accessed
[in]	varname_length	Length of `varname` in bytes
[out]	value	Pointer to output char-buffer to be filled with received environment variable
[in]	value_capacity	Capacity of `value` buffer in bytes
[out]	value_used	Pointer to output variable that is set to the amount of bytes used from `value`

Returns: GATE_RESULT_* result code

◆ gate_env_get_var_map()

GATE_CORE_API gate_result_t gate_env_get_var_map ( gate_map_t * strmap )

Creates a gate_map_t<gate_string_t, gate_string_t> with all environment variables.

Parameters

[out] strmap Pointer to storage that is initialized with a new gate_map_t object

Returns: GATE_RESULT_* result code

◆ gate_env_get_workpath()

GATE_CORE_API gate_result_t gate_env_get_workpath ( gate_string_t * workpath )

Retrieves the current working directory of the process.

Parameters

[out] workpath String to be initialized with current directory path

Returns: GATE_RESULT_* result code

◆ gate_env_set_workpath()

GATE_CORE_API gate_result_t gate_env_set_workpath ( gate_string_t const * workpath )

Sets the current working directory of the process.

Parameters

[in] workpath Filesystem path of the directory to be set

Returns: GATE_RESULT_* result code

◆ gate_env_temp_rootpath()

GATE_CORE_API gate_result_t gate_env_temp_rootpath ( gate_string_t * temppath )

Returns the filesystem path of the systems TEMP directory.

Parameters

[out] temppath String to be initialized with filesystem path of TEMP directory

Returns: GATE_RESULT_* result code

◆ gate_env_home_rootpath()

GATE_CORE_API gate_result_t gate_env_home_rootpath ( gate_string_t * homepath )

Returns the filesystem path of the systems HOME directory.

Parameters

[out] homepath String to be initialized with filesystem path of HOME directory

Returns: GATE_RESULT_* result code

◆ gate_env_app_rootpath()

GATE_CORE_API gate_result_t gate_env_app_rootpath ( gate_string_t * apppath )

Returns the filesystem path of the directory where the process executable is located.

Parameters

[out] apppath String to be initialized with filesystem path of TEMP directory

Returns: GATE_RESULT_* result code

◆ gate_env_app_executable_str()

GATE_CORE_API gate_result_t gate_env_app_executable_str	(	char *	buffer,
		gate_size_t *	buffer_len )

Fills a buffer with the filesystem path of the process' executable.

Parameters

[out]	buffer	Pointer to buffer to be filled with path
[in,out]	buffer_len	Pointer to size of `buffer`, initialized with capacity and updated with the amount of used bytes

Returns: GATE_RESULT_* result code

◆ gate_env_app_executable()

GATE_CORE_API gate_result_t gate_env_app_executable ( gate_string_t * executablepath )

Returns the filesystem path of the process' executable as a string.

Parameters

[out] executablepath String to be initialized with path of the running executable

Returns: GATE_RESULT_* result code

◆ gate_env_app_executable_name_str()

GATE_CORE_API gate_result_t gate_env_app_executable_name_str	(	char *	buffer,
		gate_size_t *	buffer_len )

Fills a buffer with the filename of the process' executable.

Parameters

[out]	buffer	Pointer to buffer to be filled with executable name
[in,out]	buffer_len	Pointer to size of `buffer`, initialized with capacity and updated with the amount of used bytes

Returns: GATE_RESULT_* result code

◆ gate_env_app_executable_name()

GATE_CORE_API gate_result_t gate_env_app_executable_name ( gate_string_t * executablename )

Returns the filename of the process' executable as a string.

Parameters

[out] executablename String to be initialized with filename of the running executable

Returns: GATE_RESULT_* result code

◆ gate_env_app_configpath()

GATE_CORE_API gate_result_t gate_env_app_configpath	(	gate_string_t const *	appname,
		gate_bool_t	global_config,
		gate_string_t *	appdatapath )

Returns the filesystem path where an app can store configuration files.

Parameters

[in]	appname	Name of app thats config-folder will be retrieved (each app has its own subdirectory)
[in]	global_config	Flag that indicates if the system-global or user-local path should be retrieved.
[out]	appdatapath	String to be initialized with filesystem path of configuration directory

Returns: GATE_RESULT_* result code

◆ gate_env_data_path()

GATE_CORE_API gate_result_t gate_env_data_path	(	gate_uint32_t	dataid,
		gate_string_t *	datapath )

Returns a filesystem folder of a specific data directory of the user account running the process.

Parameters

[in]	dataid	GATE_ENV_* identifier specifying the desired data directory
[out]	datapath	String to be initialized with filesystem path of retrieved data directory

Returns: GATE_RESULT_* result code

◆ gate_env_host_name()

GATE_CORE_API gate_result_t gate_env_host_name ( gate_string_t * hostname )

Returns the name of the hosting machine running the process.

Parameters

[out] hostname String to be initialized with hostname

Returns: GATE_RESULT_* result code

◆ gate_env_user_name()

GATE_CORE_API gate_result_t gate_env_user_name ( gate_string_t * username )

Returns the name of the user account running the process.

Parameters

[out] username String to be initialized with name of user account

Returns: GATE_RESULT_* result code

◆ gate_env_shell_path()

GATE_CORE_API gate_result_t gate_env_shell_path ( gate_string_t * shellpath )

Returns the path to the default command line shell program.

Parameters

[out] username String to be initialized with name of user account

Returns: GATE_RESULT_* result code

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ GATE_ENV_DOCUMENTS

◆ GATE_ENV_PICTURES

◆ GATE_ENV_MUSIC

◆ GATE_ENV_VIDEOS

◆ GATE_ENV_DESKTOP

◆ GATE_ENV_APPDATA

Function Documentation

◆ gate_env_list_vars()

◆ gate_env_get_var()

◆ gate_env_get_var_str()

◆ gate_env_get_var_map()

◆ gate_env_get_workpath()

◆ gate_env_set_workpath()

◆ gate_env_temp_rootpath()

◆ gate_env_home_rootpath()

◆ gate_env_app_rootpath()

◆ gate_env_app_executable_str()

◆ gate_env_app_executable()

◆ gate_env_app_executable_name_str()

◆ gate_env_app_executable_name()

◆ gate_env_app_configpath()

◆ gate_env_data_path()

◆ gate_env_host_name()

◆ gate_env_user_name()

◆ gate_env_shell_path()