confstr(3C)

Synopsis

   #include <unistd.h>
   

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

Description

The sysinfo(2) and sysconf(3C) routines provide a similar class of configuration information.

The confstr function provides the following valid values for name:

_CS_ARCHITECTURE

Copy a string describing the instruction set architecture of the current system into the array pointed to by buf. For example, mc68030, i80486. These names may not match predefined names in the C language compilation system.

_CS_BUSTYPES

Copy a comma-separated list of strings describing the installed bus types on the system into the array pointed to by buf.

_CS_HOSTNAME

Copy a string that is the fully-qualified hostname (e.g., ``system.prod.caldera.com'') of the system into the array pointed to by buf. This is the same string that would be returned by the uname command's hostname parameter. Internet host names may be up to 256 bytes in length (plus the terminating null).

_CS_HW_PROVIDER

Copy a string which is the OEM manufacturer's name and product identifier of the physical hardware on which the system call is executed into the array pointed to by buf.

_CS_HW_SERIAL

Copy a string which is the ASCII representation of the hardware-specific serial number of the physical machine on which the system call is executed into the array pointed to by buf. Note that this may be implemented in Read-Only Memory, via software constants set when building the operating system, or by other means, and may contain non-numeric characters. It is anticipated that manufacturers will not issue the same ``serial number'' to more than one physical machine. The pair of strings returned by SI_HW_PROVIDER and SI_HW_SERIAL is likely to be unique across operating system implementations.

_CS_KERNEL_STAMP

Copy a string that represents the manufacturer's date stamp for the currently running operating system kernel into the array pointed to by buf.

_CS_MACHINE

Copy the string that would be returned by uname in the machine field into the array pointed to by buf. For example, i486.

_CS_OS_BASE

Copy a string that represents the base revision level of the currently running operating system into the array pointed to by buf.

_CS_OS_PROVIDER

Copy a string that represents the name of the manufacturer of the currently running operating system base into the array pointed to by buf.

_CS_RELEASE

Copy the string that would be returned by uname in the release field into the array pointed to by buf.

CS_SRPC_DOMAIN

Copies a string representing the Secure Remote Procedure Call domain name into the array pointed to by buf.

_CS_SYSNAME

Copy the string that would be returned by uname [see uname(2)] in the sysname field, into the array pointed to by buf. This is the name of the implementation of the operating system, for example, UNIX_SV.

_CS_USER_LIMIT

Copy a string that represents the maximum number of users currently configured into the operating system into the array pointed to by buf. This is a number or the keyword ``unlimited''.

_CS_VERSION

Copy the string that would be returned by uname in the version field into the array pointed to by buf. The syntax and semantics of this string are defined by the system provider.

The name value of _CS_PATH, defined in the unistd.h header, is supported by the implementation. Others may be supported. When len has a non-zero value and name has a value that is configuration-defined, confstr copies this value into the len-bytes buffer that buf is pointing to. If the string that is being returned is longer than len bytes, including the terminating null, the string is truncated to len-1 bytes by the confstr function. The result is also null-terminated.

To detect that the string has undergone a truncation process, the application makes a comparison between the value that the confstr function has returned and len. If len has the value zero and buf is a null pointer, an integer is still returned by confstr, as defined below, but it does not return a string. An unspecified result is produced if len is zero and buf is not a null pointer.

Return values

If name is invalid variable, confstr returns zero and errno is set to indicate the error. If name has a value that is not configuration-defined, confstr returns zero and errno is left unchanged.

Errors

EINVAL

The value of the argument name is invalid.

Usage

The initial reason for having this function was to provide a way of finding the configuration-defined default value for the environment variable PATH. Applications need to be able to determine the system-supplied PATH environment variable value which contains the correct search paths for the various standard utilities. This is because PATH can be altered by users so that it can include directories that may contain utilities that replace standard utilities.

Examples

   confstr(name, (char *)NULL, (size_t)0);

In the example the confstr function is being used by the application to determine how big a buffer is needed for the string value. malloc could be used to allocate a buffer to hold the string. To obtain the string, confstr must be called again. An alternative is to allocate a fixed static buffer which is large enough to hold most answers, perhaps 512 or 1024 bytes. malloc could then be used to allocate a buffer that is larger in size if it finds that this is too small.

References