confstr(3C) DG/UX R4.11MU05 confstr(3C)
NAME
confstr - obtain configurable string values
SYNOPSIS
#include <unistd.h>
sizet confstr(int name, char *buf, sizet 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:
CSPATH This is the value for the PATH environment variable
that finds all standard utilties in the ISO POSIX-2
DIS.
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
pathconf(2), sysconf(3C), unistd(4)
Licensed material--property of copyright holder(s)