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



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

NNAAMMEE
       confstr -- get configurable variables

SSYYNNOOPPSSIISS
       #include <unistd.h>

       size_t confstr(int _n_a_m_e, char *_b_u_f, size_t _l_e_n);

DDEESSCCRRIIPPTTIIOONN
       The _c_o_n_f_s_t_r() function shall return configuration-defined string
       values. Its use and purpose are similar to _s_y_s_c_o_n_f(), but it is used
       where string values rather than numeric values are returned.

       The _n_a_m_e argument represents the system variable to be queried. The
       implementation shall support the following name values, defined in
       _<_u_n_i_s_t_d_._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 _l_e_n is not 0, and if _n_a_m_e has a configuration-defined value,
       _c_o_n_f_s_t_r() shall copy that value into the _l_e_n-byte buffer pointed to by
       _b_u_f.  If the string to be returned is longer than _l_e_n bytes, including
       the terminating null, then _c_o_n_f_s_t_r() shall truncate the string to _l_e_n-1
       bytes and null-terminate the result. The application can detect that
       the string was truncated by comparing the value returned by _c_o_n_f_s_t_r()
       with _l_e_n.

       If _l_e_n is 0 and _b_u_f is a null pointer, then _c_o_n_f_s_t_r() shall still
       return the integer value as defined below, but shall not return a
       string. If _l_e_n is 0 but _b_u_f is not a null pointer, the result is
       unspecified.

       After a call to:


           confstr(_CS_V7_ENV, buf, sizeof(buf))

       the string stored in _b_u_f 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 _b_u_f after a call to:


           confstr(_CS_PATH, buf, sizeof(buf))

       can be used as a value of the _P_A_T_H environment variable that accesses
       all of the standard utilities of POSIX.1-2008, that are provided in a
       manner accessible via the _e_x_e_c family of functions, if the return value
       is less than or equal to _s_i_z_e_o_f(_b_u_f).

RREETTUURRNN VVAALLUUEE
       If _n_a_m_e has a configuration-defined value, _c_o_n_f_s_t_r() 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 _l_e_n, the string returned in _b_u_f is truncated.

       If _n_a_m_e is invalid, _c_o_n_f_s_t_r() shall return 0 and set _e_r_r_n_o to indicate
       the error.

       If _n_a_m_e does not have a configuration-defined value, _c_o_n_f_s_t_r() shall
       return 0 and leave _e_r_r_n_o unchanged.

EERRRROORRSS
       The _c_o_n_f_s_t_r() function shall fail if:

       EEIINNVVAALL The value of the _n_a_m_e argument is invalid.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
       None.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       An application can distinguish between an invalid _n_a_m_e parameter value
       and one that corresponds to a configurable variable that has no
       configuration-defined value by checking if _e_r_r_n_o is modified. This
       mirrors the behavior of _s_y_s_c_o_n_f().

       The original need for this function was to provide a way of finding the
       configuration-defined default value for the environment variable _P_A_T_H.
       Since _P_A_T_H 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 _P_A_T_H 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
       _m_a_l_l_o_c() to allocate a buffer to hold the string; and call _c_o_n_f_s_t_r()
       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 _m_a_l_l_o_c() to allocate a larger buffer if it finds
       that this is too small.

RRAATTIIOONNAALLEE
       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 _c_o_n_f_s_t_r() function with a _n_a_m_e argument of _CS_PATH returns a
       string that can be used as a _P_A_T_H environment variable setting that
       will reference the standard shell and utilities as described in the
       Shell and Utilities volume of POSIX.1-2017.

       The _c_o_n_f_s_t_r() 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.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _e_x_e_c, _f_p_a_t_h_c_o_n_f(), _s_y_s_c_o_n_f()

       The Base Definitions volume of POSIX.1-2017, <<uunniissttdd..hh>>

       The Shell and Utilities volume of POSIX.1-2017, _c_9_9

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1-2017, Standard for Information Technology --
       Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, 2018 Edition, Copyright (C) 2018 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.opengroup.org/unix/online.html .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2017                           CONFSTR(3)
