Unix/Linux Go Back    


Linux 2.6 - man page for confstr (linux section 3posix)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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

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 pur-
       pose are similar to sysconf(), but it is used where string values rather than numeric val-
       ues 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_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 corre-
       sponds  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 utili-
       ties 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 read-
       ing 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 utili-
       ties 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  applica-
       tion  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, Copyright (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 orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003				       CONFSTR(P)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 05:11 AM.