confstr(S)
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(S)
and
sysconf(S)
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(S)]
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(S),
sysinfo(S),
sysconf(S),
unistd(F),
``What system is this?'' in Porting, integration, and compatibility
© 2005 The SCO Group, Inc. All rights reserved.
SCO OpenServer Release 6.0.0 - 01 June 2005