PxConfigOpen(), PxConfigOpenCx()

Open a configuration file

Synopsis:

#include <photon/PxProto.h>

int PxConfigOpen( const char *cfgfile,
                  int mode);

PxCfgContext_t *PxConfigOpenCx(const char *cfgfile,
                               int mode);

Arguments:

cfgfile

The configuration file to open

mode

A bitfield specifying what operations may be performed on the configuration file; it consists of a combination of the following values:

PXCONFIG_READ

Open the file for reading only. The file must exist.

PXCONFIG_WRITE

Allow reading and modification of an existing config file (using PxConfigWrite*() and PxConfigDelete*()), or create a new config file if one doesn't exist.

PXCONFIG_CLEAR (formerly PXCONFIG_CREATE)

Clear the file by removing all entries and sections. This flag only applies when PXCONFIG_WRITE is set. PXCONFIG_CREATE is deprecated.

Depending on which of the above flags are set for mode, it can take a combination of these additional flags:

PXCONFIG_UNLINK

Remove the file after it's been read by calling unlink() on it. If it is a symbolic link, just the link is removed. This setting is useful for “read-once” scenarios, or if your application wishes to migrate the config file from one location to another. This flag only applies if PXCONFIG_READ is set.

PXCONFIG_HOME

Interpret cfgfile as a path relative to the user's Photon configuration path, which is always >$HOME/.ph/. If this flag is set, the real file PxConfigOpen() attempts to open is a concatenation of this path and cfgfile.

PXCONFIG_GLOBAL

Interpret cfgfile as a path relative to the system-wide Photon configuration area, which is currently is always $PHOTON_PATH/config/. If this flag is set, the real file PxConfigOpen() attempts to open is a concatenation of this path and cfgfile.

---

If you set both PXCONFIG_HOME and PXCONFIG_GLOBAL, PxConfigOpen() attempts to open the PXCONFIG_HOME file first, then the PXCONFIG_GLOBAL file. The first open to succeed causes PxConfigOpen() to return with success, and all subsequent operations are done on that file. If neither PXCONFIG_HOME nor PXCONFIG_GLOBAL are set, then cfgfile is interpreted as the full path of the file to open.

---

Library:

phexlib

Description:

These functions open the configuration file specified by cfgfile for reading and/or writing. The file should be closed using the corresponding PxConfigClose*() when the configuration procedure is complete.

With PxConfigOpen(), you may have only one configuration file open any one time. If there is a file already open, it is first closed and PxConfigOpen() attempts to open the new file regardless of whether or not the close of the old file succeeded. The return code from PxConfigOpen() in this case reflects the status of the open of the new file, and does not indicate whether or not the old file was successfully closed. To avoid this ambiguity, you should always call PxConfigClose() on an open file prior to opening a new one.

You can use PxConfigOpenCx() to open more than one configuration file. The PxCfgContext_t * returned from this function is the configuration file handle you use to manage multiple files, and you pass it as the cx argument to other PxConfig*Cx() functions.

---

PxConfigOpenCx() returns NULL if it fails to open the configuration file. It's acceptable to pass a NULL cx pointer to any of the other PxConfig*Cx () functions. In this case, PxConfigRead*Cx simply gives back the default value. The other functions return an error code and do nothing more.

---

The configuration file consists of simple text and is divided into sections, introduced by [section_name]. Each section is made up of entries (one per line) of the form:

entry_name = value

Lines (entry name and value) are currently limited to 1024 characters; lines longer than that are truncated. Comments follow #, anywhere on a line. Here's an example:

    [WWW Section]
    Heading Font  =  swiss
    Body Font     =  dutch
    Link Color    =  0000FF
    Visited Color =  008080
    Cache Size    =  10240

    [File Section]
    File Font     =  swiss12
    Print Command =  lp @
    Display Mode  =  1

---

You can use duplicate section names in configuration files, although it is not recommended. Functions such as PxConfigSection*() that directly reference a section by name, will return or operate on the first matched section in a file. To advance to the next section with the same name, you have to use PxConfigNextSection*() until you reach the desired section.

---

Returns:

PxConfigOpen():

Pt_TRUE

The given configuration file has been opened for the specified mode.

Pt_FALSE

Otherwise.

PxConfigOpenCx():

a non-NULL pointer to a valid PxCfgContext_t

The given configuration file has been opened for the specified access mode.

NULL

Otherwise.

Examples:

if (PxConfigOpen(fname, PXCONFIG_READ)) {
    // read parameters from the file
    PxConfigClose();
}

For user “joe” with home directory /home/joe, first attempt to open /home/joe/.ph/foo/bar.cfg for read. Failing that, try /usr/photon/config/foo/bar.cfg (assuming the default setting for PHOTON_PATH):

PxConfigOpen("foo/bar.cfg",PXCONFIG_READ
             | PXCONFIG_HOME | PXCONFIG_GLOBAL);

Classification:

Photon

See also:

PxConfigClose*(), PxConfigDeleteEntry*(), PxConfigDeleteSection*(), PxConfigFirstSection*(), PxConfigForceEmptySection*(), PxConfigNextSection*(), PxConfigNextString*(), PxConfigReadBool*(), PxConfigReadChar*(), PxConfigReadDouble*(), PxConfigReadInt*(), PxConfigReadLLong*(), PxConfigReadLong*(), PxConfigReadShort*(), PxConfigReadString*(), PxConfigSection*(), PxConfigWriteBool*(), PxConfigWriteChar*(), PxConfigWriteDouble*(), PxConfigWriteInt*(), PxConfigWriteLLong*(), PxConfigWriteLong*(), PxConfigWriteShort*(), PxConfigWriteString*()