envset.h File Reference

(/usr/bin/git 2023-09-06, commit: d4525ff)

Header defining data types and functions to work with sets of environment variables. More...

#include <stddef.h>
#include "confparse.h"

Include dependency graph for envset.h:

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

Go to the source code of this file.

Data Structures
struct	crinitEnvSet_t

Macros
#define	CRINIT_ENVSET_INITIAL_SIZE   128uL
#define	CRINIT_ENVSET_SIZE_INCREMENT   64uL

Typedefs
typedef struct crinitEnvSet_t	crinitEnvSet_t

Functions
int	crinitEnvSetInit (crinitEnvSet_t *es, size_t initSize, size_t sizeIncrement)
int	crinitEnvSetDestroy (crinitEnvSet_t *es)
int	crinitEnvSetDup (crinitEnvSet_t *copy, const crinitEnvSet_t *orig)
int	crinitEnvSetCreateFromConfKvList (crinitEnvSet_t *newSet, const crinitEnvSet_t *baseSet, const crinitConfKvList_t *c, const char *restrict key)
const char *	crinitEnvSetGet (const crinitEnvSet_t *es, const char *envName)
const char *	crinitEnvSetEntry (const crinitEnvSet_t *es, const size_t idx)
int	crinitEnvSetSet (crinitEnvSet_t *es, const char *envName, const char *envVal)

Detailed Description

Header defining data types and functions to work with sets of environment variables.

Macro Definition Documentation

CRINIT_ENVSET_INITIAL_SIZE

#define CRINIT_ENVSET_INITIAL_SIZE   128uL

Default initial allocation size of an environment set.

CRINIT_ENVSET_SIZE_INCREMENT

#define CRINIT_ENVSET_SIZE_INCREMENT   64uL

Default increment of the allocation size if we run out of space.

Typedef Documentation

crinitEnvSet_t

typedef struct crinitEnvSet_t crinitEnvSet_t

Data type to hold a mutable environment set.

Function Documentation

crinitEnvSetCreateFromConfKvList()

int crinitEnvSetCreateFromConfKvList	(	crinitEnvSet_t *	newSet,
		const crinitEnvSet_t *	baseSet,
		const crinitConfKvList_t *	c,
		const char *restrict	key
	)

Creates a new environment set, given a task/series config and optionally a base set.

The new set will eb initialized with the contents of the base set (or empty if NULL) and modified by any ENV_SET directives found in the config.

Parameters

newSet	The crinitEnvSet_t to create, must be uninitialized or freed via crinitEnvSetDestroy().
baseSet	The crinitEnvSet_t which serves as a base state, must be initialized or NULL if we "start from scratch".
c	The crinitConfKvList_t which may contain ENV_SET directives to be applied to the new set.
key	The configuration key to use for reading the environment set.

Returns

0 on success, -1 otherwise

crinitEnvSetDestroy()

int crinitEnvSetDestroy

(

crinitEnvSet_t *

es

)

Frees the memory associated with an environment set.

Will free all pointers allocated through crinitEnvSetInit() and crinitEnvSetSet().

Parameters

es	The environment set to free.

Returns

0 on success, -1 otherwise

crinitEnvSetDup()

int crinitEnvSetDup	(	crinitEnvSet_t *	copy,
		const crinitEnvSet_t *	orig
	)

Duplicates an environment set.

Will have the same allocation parameter and same content but point to different memory.

Parameters

copy	The crinitEnvSet_t to copy to, must be uninitialized or freed via crinitEnvSetDestroy().
orig	The crinitEnvSet_t to copy from, must have been initialized.

Returns

0 on success, -1 otherwise

crinitEnvSetEntry()

const char * crinitEnvSetEntry	(	const crinitEnvSet_t *	es,
		const size_t	idx
	)

Gets the value for a given offset in an environment set.

Parameters

es	The environment set to search in.
idx	The offset to return.

Returns

A pointer to the variable's value inside the set or NULL if the variable was not found or an error was encountered.

crinitEnvSetGet()

const char * crinitEnvSetGet	(	const crinitEnvSet_t *	es,
		const char *	envName
	)

Gets the value for a given variable from an environment set.

Parameters

es	The environment set to search in.
envName	The name of the variable to look for.

Returns

A pointer to the variable's value inside the set or NULL if the variable was not found or an error was encountered.

crinitEnvSetInit()

int crinitEnvSetInit	(	crinitEnvSet_t *	es,
		size_t	initSize,
		size_t	sizeIncrement
	)

Initializes an environment set.

Will initialize es such that crinitEnvSet_t::envp has allocated space for initSize pointers to char and crinitEnvSet_t::allocSz, crinitEnvSet_t::allocInc reflect the given parameters.

Parameters

es	The environment set to initialize.
initSize	The allocation size of the initialized environment set.
sizeIncrement	The increment to add to the allocation size if we run out of space.

crinitEnvSetSet()

int crinitEnvSetSet	(	crinitEnvSet_t *	es,
		const char *	envName,
		const char *	envVal
	)

Sets the value for a given variable in an environment set.

Creates a new variable if no variable with the given name yet exists in the set. Otherwise an existing variable with the same name will be overwritten.

If a new variable is created and the allocation size of the set is not sufficient, the set will be grown by the size increment.

Parameters

es	The environment set to be modified, must be initialized.
envName	The name of the variable to be set.
envVal	The content of the variable to be set.

Returns

0 on success, -1 otherwise