man3/confstr.3

   1 '\" t
   2 .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" Modified Sat Jul 24 19:53:02 1993 by Rik Faith (faith@cs.unc.edu)
   7 .\"
   8 .\" FIXME Many more values for 'name' are supported, some of which
   9 .\" are documented under 'info libc confstr'.
  10 .\" See <bits/confname.h> for the rest.
  11 .\" These should all be added to this page.
  12 .\" See also the POSIX.1-2001 specification of confstr()
  13 .\"
  14 .TH confstr 3 (date) "Linux man-pages (unreleased)"
  15 .SH NAME
  16 confstr \- get configuration dependent string variables
  17 .SH LIBRARY
  18 Standard C library
  19 .RI ( libc ", " \-lc )
  20 .SH SYNOPSIS
  21 .nf
  22 .B #include <unistd.h>
  23 .PP
  24 .BI "size_t confstr(int " "name" ", char " buf [. size "], size_t " size );
  25 .fi
  26 .PP
  27 .RS -4
  28 Feature Test Macro Requirements for glibc (see
  29 .BR feature_test_macros (7)):
  30 .RE
  31 .PP
  32 .BR confstr ():
  33 .nf
  34     _POSIX_C_SOURCE >= 2 || _XOPEN_SOURCE
  35 .fi
  36 .SH DESCRIPTION
  37 .BR confstr ()
  38 gets the value of configuration-dependent string variables.
  39 .PP
  40 The
  41 .I name
  42 argument is the system variable to be queried.
  43 The following variables are supported:
  44 .TP
  45 .BR _CS_GNU_LIBC_VERSION " (GNU C library only; since glibc 2.3.2)"
  46 A string which identifies the GNU C library version on this system
  47 (e.g., "glibc 2.3.4").
  48 .TP
  49 .BR _CS_GNU_LIBPTHREAD_VERSION " (GNU C library only; since glibc 2.3.2)"
  50 A string which identifies the POSIX implementation supplied by this
  51 C library (e.g., "NPTL 2.3.4" or "linuxthreads\-0.10").
  52 .TP
  53 .B _CS_PATH
  54 A value for the
  55 .B PATH
  56 variable which indicates where all the POSIX.2 standard utilities can
  57 be found.
  58 .PP
  59 If
  60 .I buf
  61 is not NULL and
  62 .I size
  63 is not zero,
  64 .BR confstr ()
  65 copies the value of the string to
  66 .I buf
  67 truncated to
  68 .I size \- 1
  69 bytes if necessary, with a null byte (\(aq\e0\(aq) as terminator.
  70 This can be detected by comparing the return value of
  71 .BR confstr ()
  72 against
  73 .IR size .
  74 .PP
  75 If
  76 .I size
  77 is zero and
  78 .I buf
  79 is NULL,
  80 .BR confstr ()
  81 just returns the value as defined below.
  82 .SH RETURN VALUE
  83 If
  84 .I name
  85 is a valid configuration variable,
  86 .BR confstr ()
  87 returns the number of bytes (including the terminating null byte)
  88 that would be required to hold the entire value of that variable.
  89 This value may be greater than
  90 .IR size ,
  91 which means that the value in
  92 .I buf
  93 is truncated.
  94 .PP
  95 If
  96 .I name
  97 is a valid configuration variable,
  98 but that variable does not have a value, then
  99 .BR confstr ()
 100 returns 0.
 101 If
 102 .I name
 103 does not correspond to a valid configuration variable,
 104 .BR confstr ()
 105 returns 0, and
 106 .I errno
 107 is set to
 108 .BR EINVAL .
 109 .SH ERRORS
 110 .TP
 111 .B EINVAL
 112 The value of
 113 .I name
 114 is invalid.
 115 .SH ATTRIBUTES
 116 For an explanation of the terms used in this section, see
 117 .BR attributes (7).
 118 .ad l
 119 .nh
 120 .TS
 121 allbox;
 122 lbx lb lb
 123 l l l.
 124 Interface       Attribute       Value
 125 T{
 126 .BR confstr ()
 127 T}      Thread safety   MT-Safe
 128 .TE
 129 .hy
 130 .ad
 131 .sp 1
 132 .SH STANDARDS
 133 POSIX.1-2001, POSIX.1-2008.
 134 .SH EXAMPLES
 135 The following code fragment determines the path where to find
 136 the POSIX.2 system utilities:
 137 .PP
 138 .in +4n
 139 .EX
 140 char *pathbuf;
 141 size_t n;
 142
 143 n = confstr(_CS_PATH, NULL, (size_t) 0);
 144 pathbuf = malloc(n);
 145 if (pathbuf == NULL)
 146     abort();
 147 confstr(_CS_PATH, pathbuf, n);
 148 .EE
 149 .in
 150 .SH SEE ALSO
 151 .BR getconf (1),
 152 .BR sh (1),
 153 .BR exec (3),
 154 .BR fpathconf (3),
 155 .BR pathconf (3),
 156 .BR sysconf (3),
 157 .BR system (3)