# confstr

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           confstr — get configurable variables
    


## SYNOPSIS



           #include <unistd.h>
    
           size_t confstr(int _name_ , char *_buf_ , size_t _len_);
    


## DESCRIPTION



           The _confstr_() function shall return configuration-defined string
           values. Its use and purpose are similar to _sysconf_(), but it is
           used where string values rather than numeric values are returned.
    
           The _name_ argument represents the system variable to be queried.
           The implementation shall support the following name values,
           defined in _< unistd.h>_.  It may support others:
    
           _CS_PATH
           _CS_POSIX_V7_ILP32_OFF32_CFLAGS
           _CS_POSIX_V7_ILP32_OFF32_LDFLAGS
           _CS_POSIX_V7_ILP32_OFF32_LIBS
           _CS_POSIX_V7_ILP32_OFFBIG_CFLAGS
           _CS_POSIX_V7_ILP32_OFFBIG_LDFLAGS
           _CS_POSIX_V7_ILP32_OFFBIG_LIBS
           _CS_POSIX_V7_LP64_OFF64_CFLAGS
           _CS_POSIX_V7_LP64_OFF64_LDFLAGS
           _CS_POSIX_V7_LP64_OFF64_LIBS
           _CS_POSIX_V7_LPBIG_OFFBIG_CFLAGS
           _CS_POSIX_V7_LPBIG_OFFBIG_LDFLAGS
           _CS_POSIX_V7_LPBIG_OFFBIG_LIBS
           _CS_POSIX_V7_THREADS_CFLAGS
           _CS_POSIX_V7_THREADS_LDFLAGS
           _CS_POSIX_V7_WIDTH_RESTRICTED_ENVS
           _CS_V7_ENV
           _CS_POSIX_V6_ILP32_OFF32_CFLAGS
           _CS_POSIX_V6_ILP32_OFF32_LDFLAGS
           _CS_POSIX_V6_ILP32_OFF32_LIBS
           _CS_POSIX_V6_ILP32_OFFBIG_CFLAGS
           _CS_POSIX_V6_ILP32_OFFBIG_LDFLAGS
           _CS_POSIX_V6_ILP32_OFFBIG_LIBS
           _CS_POSIX_V6_LP64_OFF64_CFLAGS
           _CS_POSIX_V6_LP64_OFF64_LDFLAGS
           _CS_POSIX_V6_LP64_OFF64_LIBS
           _CS_POSIX_V6_LPBIG_OFFBIG_CFLAGS
           _CS_POSIX_V6_LPBIG_OFFBIG_LDFLAGS
           _CS_POSIX_V6_LPBIG_OFFBIG_LIBS
           _CS_POSIX_V6_WIDTH_RESTRICTED_ENVS
           _CS_V6_ENV
    
           If _len_ is not 0, and if _name_ has a configuration-defined value,
           _confstr_() shall copy that value into the _len_ -byte buffer pointed
           to by _buf_.  If the string to be returned is longer than _len_ bytes,
           including the terminating null, then _confstr_() shall truncate the
           string to _len_ -1 bytes and null-terminate the result. The
           application can detect that the string was truncated by comparing
           the value returned by _confstr_() with _len_.
    
           If _len_ is 0 and _buf_ is a null pointer, then _confstr_() shall still
           return the integer value as defined below, but shall not return a
           string. If _len_ is 0 but _buf_ is not a null pointer, the result is
           unspecified.
    
           After a call to:
    
               confstr(_CS_V7_ENV, buf, sizeof(buf))
    
           the string stored in _buf_ shall contain a <space>-separated list of
           the variable=value environment variable pairs an implementation
           requires as part of specifying a conforming environment, as
           described in the implementations' conformance documentation.
    
           If the implementation supports the POSIX shell option, the string
           stored in _buf_ after a call to:
    
               confstr(_CS_PATH, buf, sizeof(buf))
    
           can be used as a value of the _PATH_ environment variable that
           accesses all of the standard utilities of POSIX.1‐2008, that are
           provided in a manner accessible via the _exec_ family of functions,
           if the return value is less than or equal to _sizeof_(_buf_).
    


## RETURN VALUE



           If _name_ has a configuration-defined value, _confstr_() shall return
           the size of buffer that would be needed to hold the entire
           configuration-defined value including the terminating null. If
           this return value is greater than _len_ , the string returned in _buf_
           is truncated.
    
           If _name_ is invalid, _confstr_() shall return 0 and set _errno_ to
           indicate the error.
    
           If _name_ does not have a configuration-defined value, _confstr_()
           shall return 0 and leave _errno_ unchanged.
    


## ERRORS



           The _confstr_() function shall fail if:
    
           **EINVAL** The value of the _name_ argument is invalid.
    
           _The following sections are informative._
    


## EXAMPLES



           None.
    


## APPLICATION USAGE



           An application can distinguish between an invalid _name_ parameter
           value and one that corresponds to a configurable variable that has
           no configuration-defined value by checking if _errno_ is modified.
           This mirrors the behavior of _sysconf_().
    
           The original need for this function was to provide a way of
           finding the configuration-defined default value for the
           environment variable _PATH_.  Since _PATH_ can be modified by the user
           to include directories that could contain utilities replacing the
           standard utilities in the Shell and Utilities volume of
           POSIX.1‐2017, applications need a way to determine the system-
           supplied _PATH_ environment variable value that contains the correct
           search path for the standard utilities.
    
           An application could use:
    
               confstr(name, (char *)NULL, (size_t)0)
    
           to find out how big a buffer is needed for the string value; use
           _malloc_() to allocate a buffer to hold the string; and call
           _confstr_() again to get the string. Alternately, it could allocate
           a fixed, static buffer that is big enough to hold most answers
           (perhaps 512 or 1024 bytes), but then use _malloc_() to allocate a
           larger buffer if it finds that this is too small.
    


## RATIONALE



           Application developers can normally determine any configuration
           variable by means of reading from the stream opened by a call to:
    
               popen("command -p getconf variable", "r");
    
           The _confstr_() function with a _name_ argument of _CS_PATH returns a
           string that can be used as a _PATH_ environment variable setting
           that will reference the standard shell and utilities as described
           in the Shell and Utilities volume of POSIX.1‐2017.
    
           The _confstr_() function copies the returned string into a buffer
           supplied by the application instead of returning a pointer to a
           string. This allows a cleaner function in some implementations
           (such as those with lightweight threads) and resolves questions
           about when the application must copy the string returned.
    


## FUTURE DIRECTIONS



           None.
    


* * *