cfgopen()

Open a configuration file

Synopsis:

#include <cfgopen.h>

int cfgopen( const char * path,
             unsigned flags,
             const char * historical,
             char * namebuf,
             int nblen );

Description:

The cfgopen() function opens the configuration file named by path. A cover function for open(), it searches several default system locations for your files based on specified characteristics.

The value of flags correspond to, and have similar limitations of, the standard open() flags. The flags value is constructed by the bitwise ORing of values from the following list, defined in the <cfgopen.h> header file. Applications must specify exactly one of these three values (file access modes) below in the value of flag:

CFGFILE_RDONLY: Open for reading only.
CFGFILE_RDWR: Open for reading and writing.
CFGFILE_WRONLY: Open for writing only.

Any combination of these flags may be specified for the value of flag:

CFGFILE_APPEND: If set, the file offset is set to the end of the file prior to each write.
CFGFILE_CREAT: If the file doesn't exist: it's created with mode 0644; the file's user ID is set to the effective user ID of the process; and the group ID is set to the effective group ID of the process or the group ID of the file's parent directory (see chmod()).
CFGFILE_EXCL: If CFGFILE_EXCL and CFGFILE_CREAT are set, and the file exists, cfgopen() fails. The check for the existence of the file and the creation of the file if it doesn't exist is atomic with respect to other processes attempting the same operation with the same filename. Specifying CFGFILE_EXCL without CFGFILE_CREAT has no effect.
CFGFILE_TRUNC: If the file exists and is a regular file, and the file is successfully opened CFGFILE_WRONLY or CFGFILE_RDWR, the file length is truncated to zero and the mode and owner are left unchanged. CFGFILE_TRUNC has no effect on FIFO or block or character special files or directories. Using CFGFILE_TRUNC with CFGFILE_RDONLY has no effect.

Search condition flags

In order to hint to the function where it should access or construct (in the case of CFGFILE_CREAT) path, there are several bits that you can specify and OR into flags. When specified, the bits are accessed using the following search order:

CFGFILE_USER_NODE

$HOME/.cfg/confstr(CS_HOSTNAME)/path

CFGFILE_USER
```
$HOME/.cfg/path 
      
```

CFGFILE_NODE

/etc/host_cfg/confstr(CS_HOSTNAME)/path

CFGFILE_GLOBAL
```
path
      
```

If the directory /etc/host_cfg doesn't exist on the system, then the following flags are transformed automatically:

CFGFILE_USER_NODE becomes CFGFILE_USER
CFGFILE_NODE becomes CFGFILE_GLOBAL

When creating a file, or opening a file for writing, only one of the above location flags may be specified. Set CFGFILE_NOFD when only the pathname to be been used is required and an fd isn't. If a directory path doesn't exist when a file is opened for creation, cfgopen() attempts to create the path.

Specifying the following arguments is optional:

historical: File to open as a last resort if none of the criteria for finding the path is met. This string works like a path search order, and allows you to search more than one location. You can also specify %H to substitute the hostname value into the string. Specify NULL to ignore this option.
namebuf: Buffer to save the pathname in. Specify NULL to ignore this option.
nblen: Length of saved pathname buffer. Specify 0 to ignore this option.

Returns:

A valid fd if CFGFILE_NOFD isn't specified, a nonnegative value if CFGFILE_NOFD is specified, or -1 if an error occurs.

Classification:

QNX 6

Safety:
Cancellation point	Yes
Interrupt handler	No
Signal handler	Yes
Thread	Yes