confstr()

Get configuration-defined string values

Synopsis:

#include <unistd.h>

size_t confstr( int name, 
                char * buf,
                size_t len );

Arguments:

name
The system variable to query; see below.
buf
A pointer to a buffer in which the function can store the value of the system variable.
len
The length of the buffer, in bytes.

Library:

libc

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

Description:

The confstr() function lets applications get or set configuration-defined string values. This is similar to the sysconf() function, but you use it to get string values, rather than numeric values. By default, the function queries and returns values in the system.

Note: In order to set a configuration string, your process must have the PROCMGR_AID_CONFSET ability enabled. For more information, see procmgr_ability().

The name argument represents the system variable to query. The values are defined in <confname.h>; at least the following name values are valid:

_CS_ARCHITECTURE
The name of the instruction set architecture for this node's CPU(s).
_CS_DOMAIN
The domain name.
_CS_HOSTNAME
The name of this node in the network.
Note: A hostname can consist only of letters, numbers, and hyphens, and must not start or end with a hyphen. For more information, see RFC 952.
_CS_HW_PROVIDER
The name of the hardware manufacturer.
_CS_HW_SERIAL
Serial number associated with the hardware.
_CS_LIBPATH
A value similar to the LD_LIBRARY_PATH environment variable that finds all standard libraries.
_CS_LOCALE
The name of the current locale.
_CS_MACHINE
This node's hardware type.
_CS_PATH
A value similar to the PATH environment variable that finds all standard utilities.
_CS_RELEASE
The current OS release level.
_CS_RESOLVE
The contents of the resolv.conf file, excluding the domain name.
_CS_SRPC_DOMAIN
The secure RPC domain.
_CS_SYSNAME
The operating system name.
_CS_TIMEZONE
Time zone string (TZ style)
_CS_VERSION
The current OS version number.

The configuration-defined value is returned in the buffer pointed to by buf, and will be ≤ len bytes long, including the terminating NULL. If the value, including the terminating NULL, is greater than len bytes long, it's truncated to len - 1 bytes and terminated with a NULL character.

To find out the length of a configuration-defined value, call confstr() with buf set to NULL and len set to 0.

To set a configuration value:

  1. OR the name of the value (e.g. _CS_HOSTNAME) with _CS_SET.
  2. Put the new value in a NULL-terminated string.
  3. Set the value of len to 0.

Returns:

A nonzero value (if a "get" is done, the value is the length of the configuration-defined value), or 0 if an error occurs (errno is set).

You can compare the confstr() return value against len to see if the configuration-defined value was truncated when retrieving a value (you can't do this when setting a value).

Errors:

EINVAL
The name argument isn't a valid configuration-defined value.
EPERM
The calling process doesn't have the required permission; see procmgr_ability().

Examples:

Print information similar to that returned by the uname() function:

#include <unistd.h>
#include <stdio.h>
#include <limits.h>

#define BUFF_SIZE (256 + 1)

int main( void )
{
    char buff[BUFF_SIZE];

    if( confstr( _CS_SYSNAME, buff, BUFF_SIZE ) > 0 ) {
        printf( "System name: %s\n", buff );
    }
    
    if( confstr( _CS_HOSTNAME, buff, BUFF_SIZE ) > 0 ) {
        printf( "Host name: %s\n", buff );
    }
    
    if( confstr( _CS_RELEASE, buff, BUFF_SIZE ) > 0 ) {
        printf( "Release: %s\n", buff );
    }
    
    if( confstr( _CS_VERSION, buff, BUFF_SIZE ) > 0 ) {
        printf( "Version: %s\n", buff );
    }
    
    if( confstr( _CS_MACHINE, buff, BUFF_SIZE ) > 0 ) {
        printf( "Machine: %s\n", buff );
    }

    if( confstr( _CS_SET | _CS_HOSTNAME, "myhostname", 0 ) != 0 ) {
        printf( "Hostname set to: %s\n", "myhostname" );
    }

    return 0;
}

Classification:

POSIX 1003.1

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

Caveats:

The confstr() function is part of a draft standard; its interface and/or behavior may change in the future.