confstr(3C)


confstr -- obtain configurable string values

Synopsis

   #include <unistd.h>
   

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

Description

The confstr function provides a way for applications to obtain string values that are configuration-defined. The argument name is the system variable that is being queried. The confstr routine copies information relating to the system on which the process is executing into the buffer pointed to by buf. len is the size of the buffer.

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 has a value that is configuration-defined, confstr returns the size of the buffer that would be needed to hold the entire configuration-defined value. If the value returned is greater than len, the string returned in buf is truncated.

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

Failure in the confstr function will occur if:

EINVAL
The value of the argument name is invalid.

Usage

An application can distinguish between a name parameter that is invalid and one that corresponds to a configurable variable that has no configuration-defined value by checking whether errno is modified. This reflects the operation of the sysconf function.

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

Here is an example of the use of confstr by an application:
   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

fpathconf(2), sysinfo(2), sysconf(3C), unistd(4),
``What system is this?'' in Porting, integration, and compatibility
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004