cfgopen()

Open a configuration file

Synopsis:

#include <cfgopen.h>

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

Arguments:

path: The name of the configuration file that you want to open.
flags: Flags that control the opening; see below.
historical: A optional 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 lets you 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: A buffer to save the pathname in. Specify NULL to ignore this option.
nblen: The length of the buffer pointed to by namebuf. Specify 0 to ignore this option.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

This function is in libc.a, but not in libc.so (in order to save space).

The cfgopen() function opens the configuration file named by path. This function is a cover function for open() that 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 file-access modes in the value of flag:

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

You can also include any combination of these bits in 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/node_name/path
CFGFILE_USER
$HOME/.cfg/path
CFGFILE_NODE
/etc/host_cfg/node_name/path
CFGFILE_GLOBAL
path

where node_name is the value you get by calling confstr() for CS_HOSTNAME.

If the directory /etc/host_cfg doesn't exist on the system, 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, you can specify only one of the above location flags. Set CFGFILE_NOFD when you need only the pathname, not the file descriptor. If a directory path doesn't exist when a file is opened for creation, cfgopen() attempts to create the path.

Returns:

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

Classification:

QNX Neutrino

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