envDefs.h File Reference

Routines to get and set EPICS environment parameters. More...

#include "libComAPI.h"

Include dependency graph for envDefs.h:

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

Go to the source code of this file.

Classes
struct	envParam
	A structure to hold a single environment parameter. More...

Typedefs
typedef struct envParam	ENV_PARAM
	A structure to hold a single environment parameter. More...

Functions
LIBCOM_API char *epicsStdCall	envGetConfigParam (const ENV_PARAM *pParam, int bufDim, char *pBuf)
	Get value of a configuration parameter. More...
LIBCOM_API const char *epicsStdCall	envGetConfigParamPtr (const ENV_PARAM *pParam)
	Get a configuration parameter's value or default string. More...
LIBCOM_API long epicsStdCall	envPrtConfigParam (const ENV_PARAM *pParam)
	Print the value of a configuration parameter. More...
LIBCOM_API long epicsStdCall	envGetInetAddrConfigParam (const ENV_PARAM *pParam, struct in_addr *pAddr)
	Get value of an inet addr config parameter. More...
LIBCOM_API long epicsStdCall	envGetDoubleConfigParam (const ENV_PARAM *pParam, double *pDouble)
	Get value of a double configuration parameter. More...
LIBCOM_API long epicsStdCall	envGetLongConfigParam (const ENV_PARAM *pParam, long *pLong)
	Get value of a long configuration parameter. More...
LIBCOM_API unsigned short epicsStdCall	envGetInetPortConfigParam (const ENV_PARAM *pEnv, unsigned short defaultPort)
	Get value of a port number configuration parameter. More...
LIBCOM_API long epicsStdCall	envGetBoolConfigParam (const ENV_PARAM *pParam, int *pBool)
	Get value of a boolean configuration parameter. More...
LIBCOM_API long epicsStdCall	epicsPrtEnvParams (void)
	Prints all configuration parameters and their current value. More...
LIBCOM_API void epicsStdCall	epicsEnvSet (const char *name, const char *value)
	Set an environment variable's value. More...
LIBCOM_API void epicsStdCall	epicsEnvUnset (const char *name)
	Clear the value of an environment variable. More...
LIBCOM_API void epicsStdCall	epicsEnvShow (const char *name)
	Print value of an environment variable, or all variables. More...

Variables
LIBCOM_API const ENV_PARAM	EPICS_CA_ADDR_LIST
LIBCOM_API const ENV_PARAM	EPICS_CA_CONN_TMO
LIBCOM_API const ENV_PARAM	EPICS_CA_AUTO_ADDR_LIST
LIBCOM_API const ENV_PARAM	EPICS_CA_REPEATER_PORT
LIBCOM_API const ENV_PARAM	EPICS_CA_SERVER_PORT
LIBCOM_API const ENV_PARAM	EPICS_CA_MAX_ARRAY_BYTES
LIBCOM_API const ENV_PARAM	EPICS_CA_AUTO_ARRAY_BYTES
LIBCOM_API const ENV_PARAM	EPICS_CA_MAX_SEARCH_PERIOD
LIBCOM_API const ENV_PARAM	EPICS_CA_NAME_SERVERS
LIBCOM_API const ENV_PARAM	EPICS_CA_MCAST_TTL
LIBCOM_API const ENV_PARAM	EPICS_CAS_INTF_ADDR_LIST
LIBCOM_API const ENV_PARAM	EPICS_CAS_IGNORE_ADDR_LIST
LIBCOM_API const ENV_PARAM	EPICS_CAS_AUTO_BEACON_ADDR_LIST
LIBCOM_API const ENV_PARAM	EPICS_CAS_BEACON_ADDR_LIST
LIBCOM_API const ENV_PARAM	EPICS_CAS_SERVER_PORT
LIBCOM_API const ENV_PARAM	EPICS_CA_BEACON_PERIOD
	deprecated More...
LIBCOM_API const ENV_PARAM	EPICS_CAS_BEACON_PERIOD
LIBCOM_API const ENV_PARAM	EPICS_CAS_BEACON_PORT
LIBCOM_API const ENV_PARAM	EPICS_BUILD_COMPILER_CLASS
LIBCOM_API const ENV_PARAM	EPICS_BUILD_OS_CLASS
LIBCOM_API const ENV_PARAM	EPICS_BUILD_TARGET_ARCH
LIBCOM_API const ENV_PARAM	EPICS_TZ
LIBCOM_API const ENV_PARAM	EPICS_TS_NTP_INET
LIBCOM_API const ENV_PARAM	EPICS_IOC_IGNORE_SERVERS
LIBCOM_API const ENV_PARAM	EPICS_IOC_LOG_PORT
LIBCOM_API const ENV_PARAM	EPICS_IOC_LOG_INET
LIBCOM_API const ENV_PARAM	EPICS_IOC_LOG_FILE_LIMIT
LIBCOM_API const ENV_PARAM	EPICS_IOC_LOG_FILE_NAME
LIBCOM_API const ENV_PARAM	EPICS_IOC_LOG_FILE_COMMAND
LIBCOM_API const ENV_PARAM	IOCSH_PS1
LIBCOM_API const ENV_PARAM	IOCSH_HISTSIZE
LIBCOM_API const ENV_PARAM	IOCSH_HISTEDIT_DISABLE
LIBCOM_API const ENV_PARAM *	env_param_list []

Detailed Description

Routines to get and set EPICS environment parameters.

Author

Roger A. Cole

This file defines environment parameters used by EPICS and the routines used to get and set those parameter values.

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>;"

Definition in file envDefs.h.

Typedef Documentation

typedef struct envParam ENV_PARAM

A structure to hold a single environment parameter.

Function Documentation

LIBCOM_API long epicsStdCall 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

Definition at line 325 of file envSubr.c.

{
    char text[20];

    if(!envGetConfigParam(pParam, sizeof(text), text))
        return -1;
    *pBool = epicsStrCaseCmp(text, "yes")==0;
    return 0;
}

LIBCOM_API char* epicsStdCall 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.

Definition at line 139 of file envSubr.c.

{
    const char *pEnv;           /* pointer to environment string */

    pEnv = envGetConfigParamPtr(pParam);
    if (!pEnv) {
        return NULL;
    }

    strncpy(pBuf, pEnv, bufDim-1);
    pBuf[bufDim-1] = '\0';

    return pBuf;
}

LIBCOM_API const char* epicsStdCall 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.

Definition at line 81 of file envSubr.c.

{
    const char *pEnv;           /* pointer to environment string */

    pEnv = getenv(pParam->name);

    if (pEnv == NULL) {
        pEnv = pParam->pdflt;
    }

    if (pEnv) {
        if (pEnv[0u] == '\0') {
            pEnv = NULL;
        }
    }

    return pEnv;
}

LIBCOM_API long epicsStdCall 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

Definition at line 191 of file envSubr.c.

{
    char        text[128];
    char        *ptext;
    int         count;

    ptext = envGetConfigParam(pParam, sizeof text, text);
    if (ptext != NULL) {
        count = epicsScanDouble(text, pDouble);
        if (count == 1) {
            return 0;
        }
        (void)fprintf(stderr,"Unable to find a real number in %s=%s\n",
                pParam->name, text);
    }

    return -1;
}

LIBCOM_API long epicsStdCall 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

Definition at line 246 of file envSubr.c.

{
    char        text[128];
    char        *ptext;
    long        status;
    struct sockaddr_in sin;

    ptext = envGetConfigParam(pParam, sizeof text, text);
    if (ptext) {
                status = aToIPAddr (text, 0u, &sin);
                if (status == 0) {
                        *pAddr = sin.sin_addr;
                        return 0;
                }
        (void)fprintf(stderr,"Unable to find an IP address or valid host name in %s=%s\n",
                                                pParam->name, text);
    }
    return -1;
}

LIBCOM_API unsigned short epicsStdCall 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.

Definition at line 398 of file envSubr.c.

{
    long        longStatus;
    long        epicsParam;

    longStatus = envGetLongConfigParam (pEnv, &epicsParam);
    if (longStatus!=0) {
        epicsParam = (long) defaultPort;
        errlogPrintf ("EPICS Environment \"%s\" integer fetch failed\n", pEnv->name);
        errlogPrintf ("setting \"%s\" = %ld\n", pEnv->name, epicsParam);
    }

    if (epicsParam<=IPPORT_USERRESERVED || epicsParam>USHRT_MAX) {
        errlogPrintf ("EPICS Environment \"%s\" out of range\n", pEnv->name);
        /*
         * Quit if the port is wrong due coding error
         */
        assert (epicsParam != (long) defaultPort);
        epicsParam = (long) defaultPort;
        errlogPrintf ("Setting \"%s\" = %ld\n", pEnv->name, epicsParam);
    }

    /*
     * ok to clip to unsigned short here because we checked the range
     */
    return (unsigned short) epicsParam;
}

LIBCOM_API long epicsStdCall 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

Definition at line 303 of file envSubr.c.

{
    char        text[128];
    char        *ptext;
    int         count;

    ptext = envGetConfigParam(pParam, sizeof text, text);
    if (ptext) {
        count = sscanf(text, "%ld", pLong);
        if (count == 1)
                return 0;
        (void)fprintf(stderr,"Unable to find an integer in %s=%s\n",
                pParam->name, text);
    }
    return -1;
}

LIBCOM_API long epicsStdCall envPrtConfigParam

(

const ENV_PARAM *

pParam

)

Print the value of a configuration parameter.

Parameters

pParam

Pointer to config param structure.

Returns

0

Definition at line 353 of file envSubr.c.

{
    const char *pVal;

    pVal = envGetConfigParamPtr(pParam);
    if (pVal == NULL)
        fprintf(stdout, "%s is undefined\n", pParam->name);
    else
        fprintf(stdout,"%s: %s\n", pParam->name, pVal);
    return 0;
}

LIBCOM_API void epicsStdCall 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.

Definition at line 35 of file osdEnv.c.

{
    if (!name) return;
    iocshEnvClear(name);
    setenv(name, value, 1);
}

LIBCOM_API void epicsStdCall epicsEnvShow

(

const char *

name

)

Print value of an environment variable, or all variables.

Parameters

name	Environment variable name, or NULL to show all.

Definition at line 55 of file osdEnv.c.

{
    if (name == NULL) {
        extern char **environ;
        char **sp;

        for (sp = environ ; (sp != NULL) && (*sp != NULL) ; sp++)
            printf ("%s\n", *sp);
    }
    else {
        const char *cp = getenv (name);
        if (cp == NULL)
            printf ("%s is not an environment variable.\n", name);
        else
            printf ("%s=%s\n", name, cp);
    }
}

LIBCOM_API void epicsStdCall epicsEnvUnset

(

const char *

name

)

Clear the value of an environment variable.

Parameters

name	Environment variable name.

Definition at line 46 of file osdEnv.c.

{
    iocshEnvClear(name);
    unsetenv(name);
}

LIBCOM_API long epicsStdCall epicsPrtEnvParams

(

void

)

Prints all configuration parameters and their current value.

Returns

0

Definition at line 384 of file envSubr.c.

{
    const ENV_PARAM **ppParam = env_param_list;

    while (*ppParam != NULL)
        envPrtConfigParam(*(ppParam++));

    return 0;
}

Variable Documentation

LIBCOM_API const ENV_PARAM* env_param_list[]

LIBCOM_API const ENV_PARAM EPICS_BUILD_COMPILER_CLASS

LIBCOM_API const ENV_PARAM EPICS_BUILD_OS_CLASS

LIBCOM_API const ENV_PARAM EPICS_BUILD_TARGET_ARCH

LIBCOM_API const ENV_PARAM EPICS_CA_ADDR_LIST

LIBCOM_API const ENV_PARAM EPICS_CA_AUTO_ADDR_LIST

LIBCOM_API const ENV_PARAM EPICS_CA_AUTO_ARRAY_BYTES

LIBCOM_API const ENV_PARAM EPICS_CA_BEACON_PERIOD

deprecated

LIBCOM_API const ENV_PARAM EPICS_CA_CONN_TMO

LIBCOM_API const ENV_PARAM EPICS_CA_MAX_ARRAY_BYTES

LIBCOM_API const ENV_PARAM EPICS_CA_MAX_SEARCH_PERIOD

LIBCOM_API const ENV_PARAM EPICS_CA_MCAST_TTL

LIBCOM_API const ENV_PARAM EPICS_CA_NAME_SERVERS

LIBCOM_API const ENV_PARAM EPICS_CA_REPEATER_PORT

LIBCOM_API const ENV_PARAM EPICS_CA_SERVER_PORT

LIBCOM_API const ENV_PARAM EPICS_CAS_AUTO_BEACON_ADDR_LIST

LIBCOM_API const ENV_PARAM EPICS_CAS_BEACON_ADDR_LIST

LIBCOM_API const ENV_PARAM EPICS_CAS_BEACON_PERIOD

LIBCOM_API const ENV_PARAM EPICS_CAS_BEACON_PORT

LIBCOM_API const ENV_PARAM EPICS_CAS_IGNORE_ADDR_LIST

LIBCOM_API const ENV_PARAM EPICS_CAS_INTF_ADDR_LIST

LIBCOM_API const ENV_PARAM EPICS_CAS_SERVER_PORT

LIBCOM_API const ENV_PARAM EPICS_IOC_IGNORE_SERVERS

LIBCOM_API const ENV_PARAM EPICS_IOC_LOG_FILE_COMMAND

LIBCOM_API const ENV_PARAM EPICS_IOC_LOG_FILE_LIMIT

LIBCOM_API const ENV_PARAM EPICS_IOC_LOG_FILE_NAME

LIBCOM_API const ENV_PARAM EPICS_IOC_LOG_INET

LIBCOM_API const ENV_PARAM EPICS_IOC_LOG_PORT

LIBCOM_API const ENV_PARAM EPICS_TS_NTP_INET

LIBCOM_API const ENV_PARAM EPICS_TZ

LIBCOM_API const ENV_PARAM IOCSH_HISTEDIT_DISABLE

LIBCOM_API const ENV_PARAM IOCSH_HISTSIZE

LIBCOM_API const ENV_PARAM IOCSH_PS1