envDefs.h
Routines to get and set EPICS environment parameters.
This file defines environment parameters used by EPICS and the routines used to get and set those parameter values.
- Author
Roger A. Cole
The ENV_PARAM’s declared here are defined in the generated file envData.c by the bldEnvData.pl Perl script, which parses this file and the build system’s CONFIG_ENV and CONFIG_SITE_ENV files. User programs can define their own environment parameters for their own use—the only caveat is that such parameters aren’t automatically setup by EPICS.
Note
bldEnvData.pl looks for “LIBCOM_API extern const ENV_PARAM <name>;”
Functions
-
char *envGetConfigParam(const ENV_PARAM *pParam, int bufDim, char *pBuf)
Get value of a configuration parameter.
Gets the value of a configuration parameter from the environment and copies it into the caller’s buffer. If the parameter isn’t set in the environment, the default value for the parameter is copied instead. If neither provides a non-empty string the buffer is set to ‘\0’ and NULL is returned.
- Parameters:
pParam – Pointer to config param structure.
bufDim – Dimension of parameter buffer
pBuf – Pointer to parameter buffer
- Returns:
Pointer to the environment variable value string, or NULL if no parameter value and default value was empty.
-
const char *envGetConfigParamPtr(const ENV_PARAM *pParam)
Get a configuration parameter’s value or default string.
- Parameters:
pParam – Pointer to config param structure.
- Returns:
Pointer to the environment variable value string, or to the default value for the parameter, or NULL if those strings were empty or not set.
-
long envPrtConfigParam(const ENV_PARAM *pParam)
Print the value of a configuration parameter.
- Parameters:
pParam – Pointer to config param structure.
- Returns:
0
-
long envGetInetAddrConfigParam(const ENV_PARAM *pParam, struct in_addr *pAddr)
Get value of an inet addr config parameter.
Gets the value of a configuration parameter and copies it into the caller’s (struct in_addr) buffer. If the configuration parameter isn’t found in the environment, the default value for that parameter will be used. The resulting string is converted from a dotted-quad format or looked up using the DNS and copied into the inet structure.
If no parameter is found and there is no default, then -1 is returned and the callers buffer is unmodified.
- Parameters:
pParam – Pointer to config param structure.
pAddr – Pointer to struct to receive inet addr.
- Returns:
0, or -1 if an error is encountered
-
long envGetDoubleConfigParam(const ENV_PARAM *pParam, double *pDouble)
Get value of a double configuration parameter.
Gets the value of a configuration parameter, converts it into a
double
value and copies that into the caller’s buffer. If the configuration parameter isn’t found in the environment, the default value for the parameter is used instead.If no parameter is found and there is no default, then -1 is returned and the callers buffer is unmodified.
- Parameters:
pParam – Pointer to config param structure.
pDouble – Pointer to place to store value.
- Returns:
0, or -1 if an error is encountered
-
long envGetLongConfigParam(const ENV_PARAM *pParam, long *pLong)
Get value of a long configuration parameter.
Gets the value of a configuration parameter, converts it into a
long
value and copies that into the caller’s buffer. If the configuration parameter isn’t found in the environment, the default value for the parameter is used instead.If no parameter is found and there is no default, then -1 is returned and the callers buffer is unmodified.
- Parameters:
pParam – Pointer to config param structure.
pLong – Pointer to place to store value.
- Returns:
0, or -1 if an error is encountered
-
unsigned short envGetInetPortConfigParam(const ENV_PARAM *pEnv, unsigned short defaultPort)
Get value of a port number configuration parameter.
Returns the value of a configuration parameter that represents an inet port number. If no environment variable is found the default parameter value is used, and if that is also unset the
defaultPort
argument returned instead. The integer value must fall between the values IPPORT_USERRESERVED and USHRT_MAX or thedefaultPort
argument will be substituted instead.- Parameters:
pEnv – Pointer to config param structure.
defaultPort – Port number to be used if environment settings invalid.
- Returns:
Port number.
-
long envGetBoolConfigParam(const ENV_PARAM *pParam, int *pBool)
Get value of a boolean configuration parameter.
Gets the value of a configuration parameter, and puts the value 0 or 1 into the caller’s buffer depending on the value. If the configuration parameter isn’t found in the environment, the default value for the parameter is used instead.
A value is treated as True (1) if it compares equal to the string “yes” with a case-independent string comparison. All other strings are treated as False (0).
If no parameter is found and there is no default, then -1 is returned and the callers buffer is unmodified.
- Parameters:
pParam – Pointer to config param structure.
pBool – Pointer to place to store value.
- Returns:
0, or -1 if an error is encountered
-
long epicsPrtEnvParams(void)
Prints all configuration parameters and their current value.
- Returns:
0
-
void epicsEnvSet(const char *name, const char *value)
Set an environment variable’s value.
The setenv() routine is not available on all operating systems. This routine provides a portable alternative for all EPICS targets.
- Parameters:
name – Environment variable name.
value – New value for environment variable.
-
void epicsEnvUnset(const char *name)
Clear the value of an environment variable.
- Parameters:
name – Environment variable name.
-
void epicsEnvShow(const char *name)
Print value of an environment variable, or all variables.
- Parameters:
name – Environment variable name, or NULL to show all.
Variables
-
struct ENV_PARAM
- #include <envDefs.h>
A structure to hold a single environment parameter.