CONFSTR(3P)                                         POSIX Programmer's Manual                                        CONFSTR(3P)



PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may differ (con-
       sult 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 val-
       ues, defined in <unistd.h>. It may support others:

       _CS_PATH
       _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_XBS5_ILP32_OFF32_CFLAGS (LEGACY)
       _CS_XBS5_ILP32_OFF32_LDFLAGS (LEGACY)
       _CS_XBS5_ILP32_OFF32_LIBS (LEGACY)
       _CS_XBS5_ILP32_OFF32_LINTFLAGS (LEGACY)
       _CS_XBS5_ILP32_OFFBIG_CFLAGS (LEGACY)
       _CS_XBS5_ILP32_OFFBIG_LDFLAGS (LEGACY)
       _CS_XBS5_ILP32_OFFBIG_LIBS (LEGACY)
       _CS_XBS5_ILP32_OFFBIG_LINTFLAGS (LEGACY)
       _CS_XBS5_LP64_OFF64_CFLAGS (LEGACY)
       _CS_XBS5_LP64_OFF64_LDFLAGS (LEGACY)
       _CS_XBS5_LP64_OFF64_LIBS (LEGACY)
       _CS_XBS5_LP64_OFF64_LINTFLAGS (LEGACY)
       _CS_XBS5_LPBIG_OFFBIG_CFLAGS (LEGACY)
       _CS_XBS5_LPBIG_OFFBIG_LDFLAGS (LEGACY)
       _CS_XBS5_LPBIG_OFFBIG_LIBS (LEGACY)
       _CS_XBS5_LPBIG_OFFBIG_LINTFLAGS (LEGACY)


       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.

       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
       IEEE Std 1003.1-2001, 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  vari-
       able 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 envi-
       ronment 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 IEEE Std 1003.1-2001, 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
       IEEE Std 1003.1-2001.

       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.

SEE ALSO
       pathconf(), sysconf(), the Base Definitions volume of IEEE Std 1003.1-2001, <unistd.h>, the Shell and Utilities volume of
       IEEE Std 1003.1-2001, c99

COPYRIGHT
       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003  Edition,  Standard  for
       Information  Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copy-
       right (C) 2001-2003 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any
       discrepancy  between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group
       Standard  is  the  referee   document.   The   original   Standard   can   be   obtained   online   at   http://www.open-
       group.org/unix/online.html .



IEEE/The Open Group                                           2003                                                   CONFSTR(3P)