confstr(3C) confstr(3C)
NAME
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. There may be be
similarities in terms of purpose and use with the sysconf
function, although confstr is used with string return values
rather than numeric return values. The argument name is the
system variable that is being queried.
The confstr function provides the following valid values for
name:
_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_HOSTNAME Copy a string that names the present host
machine into the array pointed to by buf. This
is the string that would be returned by uname in
the nodename field. This hostname or nodename
is often the name the machine is known by
locally.
The hostname is the name of this machine as a
node in some network; different networks may
have different names for the node, but
presenting the nodename to the appropriate
network Directory or name-to-address mapping
service should produce a transport end point
address. The name may not be fully qualified.
Internet host names may be up to 256 bytes in
length (plus the terminating null).
_CS_RELEASE Copy the string that would be returned by uname
in the release field into the array pointed to
by buf. Typical values might be 4.2, 4.0, 3.2.
Copyright 1994 Novell, Inc. Page 1
confstr(3C) confstr(3C)
_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.
_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_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_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.
SI_SRPC_DOMAIN
Copies the array pointed to by buf into the
Secure Remote Procedure Call domain name.
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.
Copyright 1994 Novell, Inc. Page 2
confstr(3C) confstr(3C)
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);
Copyright 1994 Novell, Inc. Page 3
confstr(3C) confstr(3C)
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), sysconf(3C), unistd(4)
Copyright 1994 Novell, Inc. Page 4