confstr()

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 (as a QNX OS extension) 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.

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_CONFIG_PATH

A colon-separated list of directories to search for configuration files.

_CS_DOMAIN

The domain name.

_CS_GRAPHICS

The graphics redirection.

_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

The 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_PAMCONF

The search path for PAM configuration files.

_CS_PAMLIB

The search path for PAM modules.

_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

The time zone string (TZ style).

_CS_V7_ENV

A space-separated list of environment variables that must be set for the QNX OS to operate in a POSIX-conformant manner. For example, if this string contains POSIXLY_CORRECT, then your system will act in a POSIX-conformant manner if the POSIXLY_CORRECT environment variable is set.

_CS_VERSION

The current OS version number.

The configuration-defined value is returned in the buffer pointed to by buf, and will be less than or equal to 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.

Setting configuration values

As a QNX OS extension, you can set a configuration value, as follows:

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:

If you're getting the value:

• If name has a configuration-defined value, confstr() returns the size of buffer that would be needed to hold the entire value, including the terminating null. If this size is greater than len, the string returned in buf is truncated.
• If name is invalid, confstr() returns 0 and sets errno to indicate the error.
• If name doesn't have a configuration-defined value, confstr() returns 0 and leaves errno unchanged.

If you're setting a value and an error occurs, confstr() returns 0 and sets errno. Any other value indicates success.

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