Section 3c - C Functions

ATMI C Function Reference

tuxreadenv(3c)

Name

tuxreadenv()—Adds variables to the environment from a file.

Synopsis

#include <atmi.h> 
int tuxreadenv(char *file, char *label)

Description

tuxreadenv() reads a file containing environment variables and adds them to the environment, independent of platform. These variables are available using tuxgetenv() and can be reset using tuxputenv().

The format of the environment file is as follows:

Any leading space or tab character on a line is ignored and is not considered in the following points.
Lines containing variables to be put into the environment are of the form:

variable=value

or set variable=value
where variable must begin with an alphabetic or underscore character and contain only alphanumeric or underscore characters, and value may contain any character except newline.

Within the value, strings of the form ${env} are expanded using variables already in the environment (forward referencing is not supported and if a value is not set, the variable is replaced with the empty string). Backslash (\) may be used to escape the dollar sign and itself. All other shell quoting and escape mechanisms are ignored and the expanded value is placed into the environment.
Lines beginning with slash (/), pound sign (#), semicolon (;), or exclamation point (!) are treated as comments and ignored. Lines beginning with other characters besides these comment characters, a left square bracket, or an alphabetic or underscore character are reserved for future use; their use is undefined.
The file is partitioned into sections by lines beginning with left square bracket ([), which acts as a label. The label will be silently truncated if longer than 31 characters. The format of a label is:

[label]

where label follows the same rules for variable above (lines with invalid label values are ignored).

Variable lines between the top of the file and the first label are put into the environment for all labels (this is the global section). Other variables are put into the environment only if the label matches the label specified for the application. A label of [] will indicate the global section.

If file is NULL, then a default filename is used. The fixed filenames are as follows:

DOS, Windows, OS2, NT: C:\TUXEDO\TUXEDO.ENV MAC: TUXEDO.ENV in the system preferences directory NETWARE: SYS:SYSTEM\TUXEDO.ENV POSIX: /usr/tuxedo/TUXEDO.ENVor /var/opt/tuxedo/TUXEDO.ENV

If label is NULL, then only variables in the global section are put into the environment. For other values of label, the global section variables plus any variables in a section matching the label are put into the environment.

An error message is printed to the userlog() if there is a memory failure, if a non-NULL filename does not exist, or if a non-NULL label does not exist.

A thread in a multithreaded application may issue a call to tuxreadenv() while running in any context state, including TPINVALIDCONTEXT.

Example

The following is an example environment file.

TUXDIR=/usr/tuxedo [application1] ;this is a comment /* this is a comment */ #this is a comment //this is a comment FIELDTBLS=app1_flds FLDTBLDIR=/usr/app1/udataobj [application2] FIELDTBLS=app2_flds FLDTBLDIR=/usr/app2/udataobj

Return Values

If tuxreadenv()cannot obtain enough space, via malloc(), for an expanded environment, or if it cannot open and read a file with a non-NULL name, it returns a non-zero integer. Otherwise, tuxreadenv() returns zero.

Portability

In the DOS, Windows, OS/2, and NetWare environments, tuxreadenv() converts all environment variable names to uppercase.