macLib.h File Reference

Text macro substitution routines. More...

#include "ellLib.h"
#include "libComAPI.h"

Include dependency graph for macLib.h:

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

Go to the source code of this file.

Classes
struct	MAC_HANDLE
	Macro substitution context, for use by macLib routines only. More...

Macros
#define	MAC_SIZE   256
	Maximum size of a macro name or value. More...

Functions
Core Library
The core library provides a minimal set of basic operations.
LIBCOM_API long epicsStdCall	macCreateHandle (MAC_HANDLE **handle, const char *pairs[])
	Creates a new macro substitution context. More...
LIBCOM_API void epicsStdCall	macSuppressWarning (MAC_HANDLE *handle, int falseTrue)
	Disable or enable warning messages. More...
LIBCOM_API long epicsStdCall	macExpandString (MAC_HANDLE *handle, const char *src, char *dest, long capacity)
	Expand a string which may contain macro references. More...
LIBCOM_API long epicsStdCall	macPutValue (MAC_HANDLE *handle, const char *name, const char *value)
	Sets the value of a specific macro. More...
LIBCOM_API long epicsStdCall	macGetValue (MAC_HANDLE *handle, const char *name, char *value, long capacity)
	Returns the value of a macro. More...
LIBCOM_API long epicsStdCall	macDeleteHandle (MAC_HANDLE *handle)
	Marks a handle invalid, and frees all storage associated with it. More...
LIBCOM_API long epicsStdCall	macPushScope (MAC_HANDLE *handle)
	Marks the start of a new scoping level. More...
LIBCOM_API long epicsStdCall	macPopScope (MAC_HANDLE *handle)
	Retrieve the last pushed scope (like stack operations) More...
LIBCOM_API long epicsStdCall	macReportMacros (MAC_HANDLE *handle)
	Reports details of current definitions. More...
Utility Library
These convenience functions are intended for applications to use and provide a more convenient interface for some purposes.
LIBCOM_API long epicsStdCall	macParseDefns (MAC_HANDLE *handle, const char *defns, char **pairs[])
	Parse macro definitions into an array of {name, value} pairs. More...
LIBCOM_API long epicsStdCall	macInstallMacros (MAC_HANDLE *handle, char *pairs[])
	Install set of {name, value} pairs as definitions. More...
LIBCOM_API char *epicsStdCall	macEnvExpand (const char *str)
	Expand environment variables in a string. More...
LIBCOM_API char *epicsStdCall	macDefExpand (const char *str, MAC_HANDLE *macros)
	Expands macros and environment variables in a string. More...

Detailed Description

Text macro substitution routines.

Author

William Lupton, W. M. Keck Observatory

This general purpose macro substitution library is used for all macro substitutions in EPICS Base.

Most routines return 0 (OK) on success, -1 (ERROR) on failure, or small positive values for extra info. The macGetValue() and macExpandString() routines depart from this and return information both on success / failure and on value length. Errors and warnings are reported using errlogPrintf().

Definition in file macLib.h.

Macro Definition Documentation

#define MAC_SIZE   256

Maximum size of a macro name or value.

Definition at line 36 of file macLib.h.

Function Documentation

LIBCOM_API long epicsStdCall macCreateHandle	(	MAC_HANDLE **	handle,
		const char *	pairs[]
	)

Creates a new macro substitution context.

Returns

0 = OK; <0 = ERROR

Parameters

handle	pointer to variable to receive pointer to new macro substitution context
pairs	pointer to NULL-terminated array of {name,value} pair strings. A NULL value implies undefined; a NULL pairs argument implies no macros.

Definition at line 100 of file macCore.c.

{
    MAC_HANDLE *handle;         /* pointer to macro substitution context */

    /* ensure NULL handle pointer is returned on error */
    *pHandle = NULL;

    /* allocate macro substitution context */
    handle = ( MAC_HANDLE * ) dbmfMalloc( sizeof( MAC_HANDLE ) );
    if ( handle == NULL ) {
        errlogPrintf( "macCreateHandle: failed to allocate context\n" );
        return -1;
    }

    /* initialize context */
    handle->magic = MAC_MAGIC;
    handle->dirty = FALSE;
    handle->level = 0;
    handle->debug = 0;
    handle->flags = 0;
    ellInit( &handle->list );

    /* use environment variables if so specified */
    if (pairs && pairs[0] && !strcmp(pairs[0],"") && pairs[1] && !strcmp(pairs[1],"environ") && !pairs[3]) {
        handle->flags |= FLAG_USE_ENVIRONMENT;
    }
    else {
        /* if supplied, load macro definitions */
        for ( ; pairs && pairs[0]; pairs += 2 ) {
            if ( macPutValue( handle, pairs[0], pairs[1] ) < 0 ) {
                dbmfFree( handle );
                return -1;
            }
        }
    }

    /* set returned handle pointer */
    *pHandle = handle;

    return 0;
}

LIBCOM_API char* epicsStdCall macDefExpand	(	const char *	str,
		MAC_HANDLE *	macros
	)

Expands macros and environment variables in a string.

Returns

Expanded string; NULL if any undefined macros were used.

This routine is similar to macEnvExpand() but allows an optional handle to be passed in that may contain additional macro definitions. These macros are appended to the set of macros from environment variables when expanding the string.

Parameters

str	string to be expanded
macros	opaque handle; may be NULL if only environment variables are to be used

Definition at line 26 of file macEnv.c.

{
    MAC_HANDLE *handle;
    static const char * pairs[] = { "", "environ", NULL, NULL };
    long destCapacity = 128;
    char *dest = NULL;
    int n;

    if (macros) {
        handle = macros;
    } else {
        if (macCreateHandle(&handle, pairs)){
            errlogMessage("macDefExpand: macCreateHandle failed.");
            return NULL;
        }
    }

    do {
        destCapacity *= 2;
        /*
         * Use free/malloc rather than realloc since there's no need to
         * keep the original contents.
         */
        free(dest);
        dest = malloc(destCapacity);
        if(!dest)
            goto done;

        n = macExpandString(handle, str, dest, destCapacity);
    } while (n >= (destCapacity - 1));

    if (n < 0) {
        free(dest);
        dest = NULL;
    } else {
        size_t unused = destCapacity - ++n;

        if (unused >= 20)
            dest = realloc(dest, n);
    }

done:
    if (macros == NULL) {
        if (macDeleteHandle(handle)) {
            errlogMessage("macDefExpand: macDeleteHandle failed.");
        }
    }
    return dest;
}

LIBCOM_API long epicsStdCall macDeleteHandle

(

MAC_HANDLE *

handle

)

Marks a handle invalid, and frees all storage associated with it.

Returns

0 = OK; <0 = ERROR

Note

Note that this does not free any strings into which macro values have been returned. Macro values are always returned into strings which were pre-allocated by the caller.

Parameters

handle

opaque handle

Definition at line 360 of file macCore.c.

{
    MAC_ENTRY *entry, *nextEntry;

    /* check handle */
    if ( handle == NULL || handle->magic != MAC_MAGIC ) {
        errlogPrintf( "macDeleteHandle: NULL or invalid handle\n" );
        return -1;
    }

    /* debug output */
    if ( handle->debug & 1 )
        printf( "macDeleteHandle()\n" );

    /* delete all entries */
    for ( entry = first( handle ); entry != NULL; entry = nextEntry ) {
        nextEntry = next( entry );
        delete( handle, entry );
    }

    /* clear magic field and free context structure */
    handle->magic = 0;
    dbmfFree( handle );

    return 0;
}

LIBCOM_API char* epicsStdCall macEnvExpand

(

const char *

str

)

Expand environment variables in a string.

Returns

Expanded string; NULL if any undefined macros were used.

This routine expands a string which may contain macros that are environment variables. It parses the string looking for such references and passes them to macGetValue() for translation. It uses malloc() to allocate space for the expanded string and returns a pointer to this null-terminated string. It returns NULL if the source string contains any undefined references.

Parameters

str	string to be expanded

Definition at line 20 of file macEnv.c.

{
    return macDefExpand(str, NULL);
}

LIBCOM_API long epicsStdCall macExpandString	(	MAC_HANDLE *	handle,
		const char *	src,
		char *	dest,
		long	capacity
	)

Expand a string which may contain macro references.

Returns

Returns the length of the expanded string, <0 if any macro are undefined

This routine parses the src string looking for macro references and passes any it finds to macGetValue() for translation.

Note

The return value is similar to that of macGetValue(). Its absolute value is the number of characters copied to dest. If the return value is negative, at least one undefined macro was left unexpanded.

Parameters

handle	opaque handle
src	source string
dest	destination string
capacity	capacity of destination buffer (dest)

Definition at line 174 of file macCore.c.

{
    MAC_ENTRY entry;
    const char *s;
    char *d;
    long length;

    /* check handle */
    if ( handle == NULL || handle->magic != MAC_MAGIC ) {
        errlogPrintf( "macExpandString: NULL or invalid handle\n" );
        return -1;
    }

    /* debug output */
    if ( handle->debug & 1 )
        printf( "macExpandString( %s, capacity = %ld )\n", src, capacity );

    /* Check size */
    if (capacity <= 1)
        return -1;

    /* expand raw values if necessary */
    if ( expand( handle ) < 0 )
        errlogPrintf( "macExpandString: failed to expand raw values\n" );

    /* fill in necessary fields in fake macro entry structure */
    entry.name  = (char *) src;
    entry.type  = "string";
    entry.error = FALSE;

    /* expand the string */
    s  = src;
    d  = dest;
    *d = '\0';
    trans( handle, &entry, 0, "", &s, &d, d + capacity - 1 );

    /* return +/- #chars copied depending on successful expansion */
    length = d - dest;
    length = ( entry.error ) ? -length : length;

    /* debug output */
    if ( handle->debug & 1 )
        printf( "macExpandString() -> %ld\n", length );

    return length;
}

LIBCOM_API long epicsStdCall macGetValue	(	MAC_HANDLE *	handle,
		const char *	name,
		char *	value,
		long	capacity
	)

Returns the value of a macro.

Returns

Returns the length of the value string, <0 if undefined

value will be zero-terminated if the length of the value is less than capacity. The return value is the number of characters copied to value (see below for behavior if the macro is undefined). If capacity is zero, no characters will be copied to value (which may be NULL) and the call can be used to check whether the macro is defined.

Note

Truncation of the value is not reported, applications should assume that truncation has occurred if the return value is equal to capacity.

If the macro is undefined, the macro reference will be returned in the value string (if permitted by maxlen) and the function value will be minus the number of characters copied. Note that treatment of capacity is intended to be consistent with the strncpy() routine.

If the value contains macro references, these references will be expanded recursively. This expansion will detect a direct or indirect self reference.

Macro references begin with a "$" immediately followed by either a "(" or a "{" character. The macro name comes next, and may optionally be succeeded by an "=" and a default value, which will be returned if the named macro is undefined at the moment of expansion. A reference is terminated by the matching ")" or "}" character.

Parameters

handle	opaque handle
name	macro name or reference
value	string to receive macro value or name argument if macro is undefined
capacity	capacity of destination buffer (value)

Definition at line 301 of file macCore.c.

{
    MAC_ENTRY   *entry;         /* pointer to this macro's entry structure */
    long        length;         /* number of characters returned */

    /* check handle */
    if ( handle == NULL || handle->magic != MAC_MAGIC ) {
        errlogPrintf( "macGetValue: NULL or invalid handle\n" );
        return -1;
    }

    /* debug output */
    if ( handle->debug & 1 )
        printf( "macGetValue( %s )\n", name );

    /* look up macro name */
    entry = lookup( handle, name, FALSE );

    /* if capacity <= 1 or VALUE == NULL just return -1 / 0 for undefined /
       defined macro */
    if ( capacity <= 1 || value == NULL ) {
        return ( entry == NULL ) ? -1 : 0;
    }

    /* if not found, copy name to value and return minus #chars copied */
    if ( entry == NULL ) {
        strncpy( value, name, capacity );
        return ( value[capacity-1] == '\0' ) ? - (long) strlen( name ) : -capacity;
    }

    /* expand raw values if necessary; if fail (can only fail because of
       memory allocation failure), return same as if not found */
    if ( expand( handle ) < 0 ) {
        errlogPrintf( "macGetValue: failed to expand raw values\n" );
        strncpy( value, name, capacity );
        return ( value[capacity-1] == '\0' ) ? - (long) strlen( name ) : -capacity;
    }

    /* copy value and return +/- #chars copied depending on successful
       expansion */
    strncpy( value, entry->value, capacity );
    length = ( value[capacity-1] == '\0' ) ? entry->length : capacity;

    return ( entry->error ) ? -length : length;
}

LIBCOM_API long epicsStdCall macInstallMacros	(	MAC_HANDLE *	handle,
		char *	pairs[]
	)

Install set of {name, value} pairs as definitions.

Returns

Number of macros defined; <0 = ERROR

This takes an array of pairs as defined above and installs them as definitions by calling macPutValue(). The pairs array is terminated by a NULL pointer.

Parameters

handle	opaque handle
pairs	pointer to NULL-terminated array of {name,value} pair strings; a NULL value implies undefined; a NULL argument implies no macros

Definition at line 253 of file macUtil.c.

{
    int n;
    char **p;

    /* debug output */
    if ( handle->debug & 1 )
        printf( "macInstallMacros( %s, %s, ... )\n",
                pairs && pairs[0] ? pairs[0] : "NULL",
                pairs && pairs[1] ? pairs[1] : "NULL" );

    /* go through array defining macros */
    for ( n = 0, p = pairs; p != NULL && p[0] != NULL; n++, p += 2 ) {
        if ( macPutValue( handle, p[0], p[1] ) < 0 )
            return -1;
    }

    /* debug output */
    if ( handle->debug & 1 )
        printf( "macInstallMacros() -> %d\n", n );

    /* return number of macros defined */
    return n;
}

LIBCOM_API long epicsStdCall macParseDefns	(	MAC_HANDLE *	handle,
		const char *	defns,
		char **	pairs[]
	)

Parse macro definitions into an array of {name, value} pairs.

Returns

Number of macros found; <0 = ERROR

This takes a set of macro definitions in "a=xxx,b=yyy" format and converts them into an array of pointers to character strings which are, in order, "first name", "first value", "second name", "second value" etc. The array is terminated with two NULL pointers and all storage is allocated contiguously so that it can be freed with a single call to free().

This routine is independent of any handle and provides a generally useful service which may be used elsewhere. Any macro references in values are not expanded at this point since the referenced macros may be defined or redefined before the macro actually has to be translated.

Shell-style escapes and quotes are supported, as are things like "A=B,B=$(C$(A)),CA=CA,CB=CB" (sets B to "CB"). White space is significant within values but ignored elsewhere (i.e. surrounding "=" and "," characters).

The function returns the number of definitions encountered, or -1 if the supplied string is invalid.

Parameters

handle	opaque handle; may be NULL if debug messages are not required.
defns	macro definitions in "a=xxx,b=yyy" format
pairs	address of variable to receive pointer to NULL-terminated array of {name, value} pair strings; all storage is allocated contiguously

Definition at line 32 of file macUtil.c.

{
    static const size_t altNumMax = 4;
    size_t numMax;
    int i;
    int num;
    int quote;
    int escape;
    size_t nbytes;
    const char **ptr;
    const char **end;
    int *del;
    char *memCp, **memCpp;
    const char *c;
    char *s, *d, **p;
    enum { preName, inName, preValue, inValue } state;

    /* debug output */
    if ( handle && (handle->debug & 1) )
        printf( "macParseDefns( %s )\n", defns );

    /* allocate temporary pointer arrays; in worst case they need to have
       as many entries as the length of the defns string */
    numMax = strlen( defns );
    if ( numMax < altNumMax )
        numMax = altNumMax;
    ptr = (const char **) calloc( numMax, sizeof( char * ) );
    end = (const char **) calloc( numMax, sizeof( char * ) );
    del = (int *) calloc( numMax, sizeof( int ) );
    if ( ptr == NULL || end == NULL  || del == NULL ) goto error;

    /* go through definitions, noting pointers to starts and ends of macro
       names and values; honor quotes and escapes; ignore white space
       around assignment and separator characters */
    num    = 0;
    del[0] = FALSE;
    quote  = 0;
    state  = preName;
    for ( c = (const char *) defns; *c != '\0'; c++ ) {

        /* handle quotes */
        if ( quote )
            quote = ( *c == quote ) ? 0 : quote;
        else if ( *c == '\'' || *c == '"' )
            quote = *c;

        /* handle escapes (pointer incremented below) */
        escape = ( *c == '\\' && *( c + 1 ) != '\0' );

        switch ( state ) {
          case preName:
            if ( !quote && !escape && ( isspace( (int) *c ) || *c == ',' ) ) break;
            ptr[num] = c;
            state = inName;
            /* fall through (may be empty name) */

          case inName:
            if ( quote || escape || ( *c != '=' && *c != ',' ) ) break;
            end[num] = c;
            while ( end[num] > ptr[num] && isspace( (int) *( end[num] - 1 ) ) )
                end[num]--;
            num++;
            del[num] = FALSE;
            state = preValue;
            if ( *c != ',' ) break;
            del[num] = TRUE;
            /* fall through (','; will delete) */

          case preValue:
            if ( !quote && !escape && isspace( (int) *c ) ) break;
            ptr[num] = c;
            state = inValue;
            /* fall through (may be empty value) */

          case inValue:
            if ( quote || escape || *c != ',' ) break;
            end[num] = c;
            while ( end[num] > ptr[num] && isspace( (int) *( end[num] - 1 ) ) )
                end[num]--;
            num++;
            del[num] = FALSE;
            state = preName;
            break;
        }

        /* if this was escape, increment pointer now (couldn't do
           before because could have ignored escape at start of name
           or value) */
        if ( escape ) c++;
    }

    /* tidy up from state at end of string */
    switch ( state ) {
      case preName:
        break;
      case inName:
        end[num] = c;
        while ( end[num] > ptr[num] && isspace( (int) *( end[num] - 1 ) ) )
            end[num]--;
        num++;
        del[num] = TRUE;
      case preValue:
        ptr[num] = c;
      case inValue:
        end[num] = c;
        while ( end[num] > ptr[num] && isspace( (int) *( end[num] - 1 ) ) )
            end[num]--;
        num++;
        del[num] = FALSE;
    }

    /* debug output */
    if ( handle != NULL && handle->debug & 4 )
        for ( i = 0; i < num; i += 2 )
            printf( "[%ld] %.*s = [%ld] %.*s (%s) (%s)\n",
                    (long) (end[i+0] - ptr[i+0]), (int) (end[i+0] - ptr[i+0]), ptr[i+0],
                    (long) (end[i+1] - ptr[i+1]), (int) (end[i+1] - ptr[i+1]), ptr[i+1],
                    del[i+0] ? "del" : "nodel",
                    del[i+1] ? "del" : "nodel" );

    /* calculate how much memory to allocate: pointers followed by
       strings */
    nbytes = ( num + 2 ) * sizeof( char * );
    for ( i = 0; i < num; i++ )
        nbytes += end[i] - ptr[i] + 1;

    /* allocate memory and set returned pairs pointer */
    memCp = malloc( nbytes );
    if ( memCp == NULL ) goto error;
    memCpp = ( char ** ) memCp;
    *pairs = memCpp;

    /* copy pointers and strings (memCpp accesses the pointer section
       and memCp accesses the string section) */
    memCp += ( num + 2 ) * sizeof( char * );
    for ( i = 0; i < num; i++ ) {

        /* if no '=' followed the name, macro will be deleted */
        if ( del[i] )
            *memCpp++ = NULL;
        else
            *memCpp++ = memCp;

        /* copy value regardless of the above */
        strncpy( memCp, (const char *) ptr[i], end[i] - ptr[i] );
        memCp += end[i] - ptr[i];
        *memCp++ = '\0';
    }

    /* add two NULL pointers */
    *memCpp++ = NULL;
    *memCpp++ = NULL;

    /* remove quotes and escapes from names in place (unlike values, they
       will not be re-parsed) */
    for ( p = *pairs; *p != NULL; p += 2 ) {
        quote = 0;
        for ( s = d = *p; *s != '\0'; s++ ) {

            /* quotes are not copied */
            if ( quote ) {
                if ( *s == quote ) {
                    quote = 0;
                    continue;
                }
            }
            else if ( *s == '\'' || *s == '"' ) {
                quote = *s;
                continue;
            }

            /* escapes are not copied but next character is */
            if ( *s == '\\' && *( s + 1 ) != '\0' )
                s++;

            /* others are copied */
            *d++ = *s;
        }

        /* need to terminate destination */
        *d++ = '\0';
    }

    /* free workspace */
    free( ( void * ) ptr );
    free( ( void * ) end );
    free( ( char * ) del );

    /* debug output */
    if ( handle != NULL && handle->debug & 1 )
        printf( "macParseDefns() -> %d\n", num / 2 );

    /* success exit; return number of definitions */
    return num / 2;

    /* error exit */
error:
    errlogPrintf( "macParseDefns: failed to allocate memory\n" );
    if ( ptr != NULL ) free( ( void * ) ptr );
    if ( end != NULL ) free( ( void * ) end );
    if ( del != NULL ) free( ( char * ) del );
    *pairs = NULL;
    return -1;
}

LIBCOM_API long epicsStdCall macPopScope

(

MAC_HANDLE *

handle

)

Retrieve the last pushed scope (like stack operations)

Returns

0 = OK; <0 = ERROR

See macPushScope()

Parameters

handle

opaque handle

Definition at line 427 of file macCore.c.

{
    MAC_ENTRY *entry, *nextEntry;

    /* check handle */
    if ( handle == NULL || handle->magic != MAC_MAGIC ) {
        errlogPrintf( "macPopScope: NULL or invalid handle\n" );
        return -1;
    }

    /* debug output */
    if ( handle->debug & 1 )
        printf( "macPopScope()\n" );

    /* check scoping level isn't already zero */
    if ( handle->level == 0 ) {
        errlogPrintf( "macPopScope: no scope to pop\n" );
        return -1;
    }

    /* look up most recent scope entry */
    entry = lookup( handle, "<scope>", TRUE );
    if ( entry == NULL ) {
        errlogPrintf( "macPopScope: no scope to pop\n" );
        return -1;
    }

    /* delete scope entry and all macros defined since it */
    for ( ; entry != NULL; entry = nextEntry ) {
        nextEntry = next( entry );
        delete( handle, entry );
    }

    /* decrement scoping level */
    handle->level--;

    return 0;
}

LIBCOM_API long epicsStdCall macPushScope

(

MAC_HANDLE *

handle

)

Marks the start of a new scoping level.

Returns

0 = OK; <0 = ERROR

Marks all macro definitions added after this call as belonging to another scope. These macros will be lost on a macPopScope() call and those at the current scope will be re-instated.

Parameters

handle

opaque handle

Definition at line 392 of file macCore.c.

{
    MAC_ENTRY *entry;

    /* check handle */
    if ( handle == NULL || handle->magic != MAC_MAGIC ) {
        errlogPrintf( "macPushScope: NULL or invalid handle\n" );
        return -1;
    }

    /* debug output */
    if ( handle->debug & 1 )
        printf( "macPushScope()\n" );

    /* increment scoping level */
    handle->level++;

    /* create new "special" entry of name "<scope>" */
    entry = create( handle, "<scope>", TRUE );
    if ( entry == NULL ) {
        handle->level--;
        errlogPrintf( "macPushScope: failed to push scope\n" );
        return -1;
    } else {
        entry->type = "scope marker";
    }

    return 0;
}

LIBCOM_API long epicsStdCall macPutValue	(	MAC_HANDLE *	handle,
		const char *	name,
		const char *	value
	)

Sets the value of a specific macro.

Returns

Returns the length of the value string.

Note

If value is NULL, all instances of name are undefined at all scoping levels (the named macro doesn't have to exist in this case). Macros referenced in value need not be defined at this point.

Parameters

handle	opaque handle
name	macro name
value	macro value

Definition at line 233 of file macCore.c.

{
    MAC_ENTRY   *entry;         /* pointer to this macro's entry structure */

    /* check handle */
    if ( handle == NULL || handle->magic != MAC_MAGIC ) {
        errlogPrintf( "macPutValue: NULL or invalid handle\n" );
        return -1;
    }

    if ( handle->debug & 1 )
        printf( "macPutValue( %s, %s )\n", name, value ? value : "NULL" );

    /* handle NULL value case: if name was found, delete entry (may be
       several entries at different scoping levels) */
    if ( value == NULL ) {
        /*
         * FIXME: shouldn't be able to delete entries from lower scopes
         * NOTE: when this is changed, this functionality of removing
         * a macro from all scopes will still be needed by iocshEnvClear
         */
        while ( ( entry = lookup( handle, name, FALSE ) ) != NULL ) {
            int done = strcmp(entry->type, "environment variable") == 0;
            delete( handle, entry );

            if (done)
                break;
        }

        return 0;
    }

    /* look up macro name */
    entry = lookup( handle, name, FALSE );

    /* new entry must be created if macro doesn't exist or if it only
       exists at a lower scoping level */
    if ( entry == NULL || entry->level < handle->level ) {
        entry = create( handle, name, FALSE );
        if ( entry == NULL ) {
            errlogPrintf( "macPutValue: failed to create macro %s = %s\n",
                            name, value );
            return -1;
        } else {
            entry->type = "macro";
        }
    }

    /* copy raw value */
    if ( rawval( handle, entry, value ) == NULL ) {
        errlogPrintf( "macPutValue: failed to copy macro %s = %s\n",
                        name, value ) ;
        return -1;
    }

    /* return length of value */
    return strlen( value );
}

LIBCOM_API long epicsStdCall macReportMacros

(

MAC_HANDLE *

handle

)

Reports details of current definitions.

Returns

0 = OK; <0 = ERROR This sends details of current definitions to standard output, and is intended purely for debugging purposes.

Parameters

handle

opaque handle

Definition at line 471 of file macCore.c.

{
    const char *format = "%-1s %-16s %-16s %s\n";
    MAC_ENTRY *entry;

    /* check handle */
    if ( handle == NULL || handle->magic != MAC_MAGIC ) {
        errlogPrintf( "macReportMacros: NULL or invalid handle\n" );
        return -1;
    }

    /* expand raw values if necessary; report but ignore failure */
    if ( expand( handle ) < 0 )
        errlogPrintf( "macGetValue: failed to expand raw values\n" );

    /* loop through macros, reporting names and values */
    printf( format, "e", "name", "rawval", "value" );
    printf( format, "-", "----", "------", "-----" );
    for ( entry = first( handle ); entry != NULL; entry = next( entry ) ) {

        /* differentiate between "special" (scope marker) and ordinary
           entries */
        if ( entry->special )
            printf( format, "s", "----", "------", "-----" );
        else
            printf( format, entry->error ? "*" : " ", entry->name,
                         entry->rawval ? entry->rawval : "",
                         entry->value  ? entry->value  : "");
    }

    return 0;
}

LIBCOM_API void epicsStdCall macSuppressWarning	(	MAC_HANDLE *	handle,
		int	falseTrue
	)

Disable or enable warning messages.

The macExpandString() routine prints warnings when it cant expand a macro. This routine can be used to silence those warnings. A non zero value will suppress the warning messages from subsequent library routines given the same handle.

Parameters

handle	opaque handle
falseTrue	0 means issue, 1 means suppress

Definition at line 154 of file macCore.c.

{
    if ( handle && handle->magic == MAC_MAGIC ) {
        handle->flags = (handle->flags & ~FLAG_SUPPRESS_WARNINGS) |
                        (suppress ? FLAG_SUPPRESS_WARNINGS : 0);
    }
}