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 the defaultPort 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

const ENV_PARAM EPICS_CA_ADDR_LIST
const ENV_PARAM EPICS_CA_CONN_TMO
const ENV_PARAM EPICS_CA_AUTO_ADDR_LIST
const ENV_PARAM EPICS_CA_REPEATER_PORT
const ENV_PARAM EPICS_CA_SERVER_PORT
const ENV_PARAM EPICS_CA_MAX_ARRAY_BYTES
const ENV_PARAM EPICS_CA_AUTO_ARRAY_BYTES
const ENV_PARAM EPICS_CA_MAX_SEARCH_PERIOD
const ENV_PARAM EPICS_CA_NAME_SERVERS
const ENV_PARAM EPICS_CA_MCAST_TTL
const ENV_PARAM EPICS_CAS_INTF_ADDR_LIST
const ENV_PARAM EPICS_CAS_IGNORE_ADDR_LIST
const ENV_PARAM EPICS_CAS_AUTO_BEACON_ADDR_LIST
const ENV_PARAM EPICS_CAS_BEACON_ADDR_LIST
const ENV_PARAM EPICS_CAS_SERVER_PORT
const ENV_PARAM EPICS_CA_BEACON_PERIOD

deprecated

const ENV_PARAM EPICS_CAS_BEACON_PERIOD
const ENV_PARAM EPICS_CAS_BEACON_PORT
const ENV_PARAM EPICS_BUILD_COMPILER_CLASS
const ENV_PARAM EPICS_BUILD_OS_CLASS
const ENV_PARAM EPICS_BUILD_TARGET_ARCH
const ENV_PARAM EPICS_TZ
const ENV_PARAM EPICS_TS_NTP_INET
const ENV_PARAM EPICS_IOC_IGNORE_SERVERS
const ENV_PARAM EPICS_IOC_LOG_PORT
const ENV_PARAM EPICS_IOC_LOG_INET
const ENV_PARAM EPICS_IOC_LOG_FILE_LIMIT
const ENV_PARAM EPICS_IOC_LOG_FILE_NAME
const ENV_PARAM EPICS_IOC_LOG_FILE_COMMAND
const ENV_PARAM IOCSH_PS1
const ENV_PARAM IOCSH_HISTSIZE
const ENV_PARAM IOCSH_HISTEDIT_DISABLE
const ENV_PARAM EPICS_ABORT_ON_ASSERT
const ENV_PARAM *env_param_list[]
struct ENV_PARAM
#include <envDefs.h>

A structure to hold a single environment parameter.

Public Members

char *name

Name of the parameter.

char *pdflt

Default value.