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 (as a QNX Neutrino 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.
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_CONFIG_PATH
- A colon-separated list of directories to search for configuration files.
- _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 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.
As a QNX Neutrino extension, you can set a configuration value, as follows:
- OR the name of the value (e.g., _CS_HOSTNAME) with _CS_SET.
- Put the new value in a NULL-terminated string.
- 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
Safety: |
|
Cancellation point |
No |
Interrupt handler |
No |
Signal handler |
Yes |
Thread |
Yes |