Environment manipulation¶

enum mm_known_dir¶

enum mm_known_dir¶: identifier of base folder

Definition¶

enum mm_known_dir {
    MM_HOME,
    MM_DATA_HOME,
    MM_CONFIG_HOME,
    MM_CACHE_HOME,
    MM_RUNTIME_DIR,
    MM_NUM_DIRTYPE
};

Constants¶

MM_HOME: home folder of user
MM_DATA_HOME: user-specific data files
MM_CONFIG_HOME: user-specific configuration files
MM_CACHE_HOME: user-specific non-essential (cached) data
MM_RUNTIME_DIR: where user-specific runtime files and other objects should be placed.
MM_NUM_DIRTYPE: do not use (for internals of mmlib only)

mm_getenv¶

#include <mmlib.h>

const char* mm_getenv(const char* name, const char* default_value)¶

Return environment variable or default value

Parameters:	name (const char) – name of the environment variable default_value* (const char*) – default value

Return¶

the value set in the environment if the variable name is set. Otherwise default_value is returned.

mm_setenv¶

#include <mmlib.h>

int mm_setenv(const char* name, const char* value, int action)¶

Add or change environment variable

Parameters:	name (const char) – name of the environment variable value* (const char) – value to set the environment variable called `name` action* (int) – set to 0 if only add is permitted

Description¶

This updates or adds a variable in the environment of the calling process. The name argument points to a string containing the name of an environment variable to be added or altered. The environment variable will be set to the value to which value points. If the environment variable named by name already exists, behavior is determined by the value of the action variable.

If the value of action is 0, the function shall return success and the environment shall remain unchanged. If the value of action is 1/MM_ENV_OVERWRITE, the function overwrites the environment and returns. If the value of action is 2/MM_ENV_PREPEND, the function prepends the value to the environment. If the value of action is 3/MM_ENV_APPEND, the function appends the value to the environment.

Note¶

the PREPEND and APPEND actions only make sense when used with PATH-like environment variables

Return¶

0 in case of success, -1 otherwise with error state set accordingly.

mm_unsetenv¶

#include <mmlib.h>

int mm_unsetenv(const char* name)¶

remove an environment variable

Parameters:	name (const char*) – name of environment variable to remove

Description¶

This function removes an environment variable from the environment of the calling process. The name argument points to a string, which is the name of the variable to be removed. If the named variable does not exist in the current environment, the environment shall be unchanged and the function is considered to have completed successfully.

Return¶

0 in case of success, -1 otherwise with error state set accordingly.

mm_get_environ¶

#include <mmlib.h>

char const* const* mm_get_environ(void)¶

get array of environment variables

Parameters:	void – no arguments

Description¶

This function gets an NULL-terminated array of strings corresponding to the environment of the current process. Each string has the format “key=val” where key is the name of the environment variable and val its value.

NOTE¶

The array and its content is valid until the environment is modified, ie until any environment variable is added, modified or removed.

Return¶

a NULL terminated array of “key=val” environment strings.

mm_get_basedir¶

#include <mmlib.h>

const char* mm_get_basedir(enum mm_known_dir dirtype)¶

get location of standard base folder

Parameters:	dirtype (enum mm_known_dir) – `enum mm_known_dir` value specifying the base folder to get

Description¶

The base folder provided follow the XDG base directory specification https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html. As such, the reported folder can be controlled through environment variables.

Return¶

pointer to the corresponding string in case of success, NULL otherwise with error state set accordingly. If dirtype is valid, the function cannot fail.

mm_path_from_basedir¶

#include <mmlib.h>

char* mm_path_from_basedir(enum mm_known_dir dirtype, const char* suffix)¶

form a path using a standard base folder

Parameters:	dirtype (enum mm_known_dir) – `enum mm_known_dir` value specifying the base folder suffix (const char*) – path to append to base folder

Return¶

pointer to allocated string containing the specified path in case of success, NULL with error state set accordingly otherwise. The allocated string must be freed by a call to free() when it is no longer needed.

mm_basename¶

#include <mmlib.h>

int mm_basename(char* base, const char* path)¶

get basename of a path

Parameters:	base (char) – string buffer receiving the result (may be NULL) path* (const char*) – path whose basename must be computed (may be NULL)

Description¶

This function takes the pathname pointed to by path and write in base (if not NULL) the final component of the pathname, deleting any trailing path separator characters (‘/’ on POSIX, ‘/’ and ‘' on Windows). If base is NULL, the result is not written, only the number of character needed by the resulting string is returned.

If path is NULL or “”, the resulting basename will be “.”;

Thr pointer base and path need not be different: it is legal to use the same buffer for both (thus realizing an inplace transformation of the path). More generally, base and path may overlap. Also contrary to its POSIX equivalent, this function is guaranteed to be reentrant.

NOTE¶

If allocated length for base is greater or equal to length of path (including null terminator) with a minimum of 2, then it is guaranteed that the result will not overflow base.

Return¶

the number of character (excluding null termination) that are written to base (or would be written if base is NULL)

mm_dirname¶

#include <mmlib.h>

int mm_dirname(char* dir, const char* path)¶

get directory name of a path

Parameters:	dir (char) – string buffer receiving the result (may be NULL) path* (const char*) – path whose dirname must be computed (may be NULL)

Description¶

This takes a pointer to a character string path that contains a pathname, and write the pathname of the parent directory of that file in the buffer pointed to by dir (if not NULL). This does not perform pathname resolution; the result will not be affected by whether or not path exists or by its file type. Trailing path separator (‘/’ on POSIX, ‘/’ and ‘' on Windows) not also leading characters are not counted as part of the path. If dir is NULL, the result is not written, only the number of character needed by the resulting string is returned.

If path is NULL or “”, the resulting dirname will be “.”;

The pointers dir and path need not be different: it is legal to use the same buffer for both (thus realizing an inplace transformation of the path). More generally, dir and path may overlap. Also contrary to its POSIX equivalent, this function is guaranteed to be reentrant.

NOTE¶

If allocated length for dir is greater or equal to length of path (including null terminator) with a minimum of 2, then it is guaranteed that the result will not overflow dir.

Return¶

the number of character (excluding null termination) that are written to dir (or would be written if dir is NULL)