man3/confstr.3

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