logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

confstr.3p (7256B)


  1. '\" et
  2. .TH CONFSTR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. confstr
  12. \(em get configurable variables
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <unistd.h>
  17. .P
  18. size_t confstr(int \fIname\fP, char *\fIbuf\fP, size_t \fIlen\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIconfstr\fR()
  23. function shall return configuration-defined string values. Its use and
  24. purpose are similar to
  25. \fIsysconf\fR(),
  26. but it is used where string values rather than numeric values are
  27. returned.
  28. .P
  29. The
  30. .IR name
  31. argument represents the system variable to be queried. The
  32. implementation shall support the following name values, defined in
  33. .IR <unistd.h> .
  34. It may support others:
  35. .P
  36. .nf
  37. _CS_PATH
  38. _CS_POSIX_V7_ILP32_OFF32_CFLAGS
  39. _CS_POSIX_V7_ILP32_OFF32_LDFLAGS
  40. _CS_POSIX_V7_ILP32_OFF32_LIBS
  41. _CS_POSIX_V7_ILP32_OFFBIG_CFLAGS
  42. _CS_POSIX_V7_ILP32_OFFBIG_LDFLAGS
  43. _CS_POSIX_V7_ILP32_OFFBIG_LIBS
  44. _CS_POSIX_V7_LP64_OFF64_CFLAGS
  45. _CS_POSIX_V7_LP64_OFF64_LDFLAGS
  46. _CS_POSIX_V7_LP64_OFF64_LIBS
  47. _CS_POSIX_V7_LPBIG_OFFBIG_CFLAGS
  48. _CS_POSIX_V7_LPBIG_OFFBIG_LDFLAGS
  49. _CS_POSIX_V7_LPBIG_OFFBIG_LIBS
  50. _CS_POSIX_V7_THREADS_CFLAGS
  51. _CS_POSIX_V7_THREADS_LDFLAGS
  52. _CS_POSIX_V7_WIDTH_RESTRICTED_ENVS
  53. _CS_V7_ENV
  54. _CS_POSIX_V6_ILP32_OFF32_CFLAGS
  55. _CS_POSIX_V6_ILP32_OFF32_LDFLAGS
  56. _CS_POSIX_V6_ILP32_OFF32_LIBS
  57. _CS_POSIX_V6_ILP32_OFFBIG_CFLAGS
  58. _CS_POSIX_V6_ILP32_OFFBIG_LDFLAGS
  59. _CS_POSIX_V6_ILP32_OFFBIG_LIBS
  60. _CS_POSIX_V6_LP64_OFF64_CFLAGS
  61. _CS_POSIX_V6_LP64_OFF64_LDFLAGS
  62. _CS_POSIX_V6_LP64_OFF64_LIBS
  63. _CS_POSIX_V6_LPBIG_OFFBIG_CFLAGS
  64. _CS_POSIX_V6_LPBIG_OFFBIG_LDFLAGS
  65. _CS_POSIX_V6_LPBIG_OFFBIG_LIBS
  66. _CS_POSIX_V6_WIDTH_RESTRICTED_ENVS
  67. _CS_V6_ENV
  68. .fi
  69. .P
  70. If
  71. .IR len
  72. is not 0, and if
  73. .IR name
  74. has a configuration-defined value,
  75. \fIconfstr\fR()
  76. shall copy that value into the
  77. .IR len -byte
  78. buffer pointed to by
  79. .IR buf .
  80. If the string to be returned is longer than
  81. .IR len
  82. bytes, including the terminating null, then
  83. \fIconfstr\fR()
  84. shall truncate the string to
  85. .IR len \-1
  86. bytes and null-terminate the result. The application can detect that
  87. the string was truncated by comparing the value returned by
  88. \fIconfstr\fR()
  89. with
  90. .IR len .
  91. .P
  92. If
  93. .IR len
  94. is 0 and
  95. .IR buf
  96. is a null pointer, then
  97. \fIconfstr\fR()
  98. shall still return the integer value as defined below, but shall not
  99. return a string. If
  100. .IR len
  101. is 0 but
  102. .IR buf
  103. is not a null pointer, the result is unspecified.
  104. .P
  105. After a call to:
  106. .sp
  107. .RS 4
  108. .nf
  109. confstr(_CS_V7_ENV, buf, sizeof(buf))
  110. .fi
  111. .P
  112. .RE
  113. .P
  114. the string stored in
  115. .IR buf
  116. shall contain a
  117. <space>-separated
  118. list of the variable=value environment variable pairs an
  119. implementation requires as part of specifying a conforming
  120. environment, as described in the implementations' conformance
  121. documentation.
  122. .P
  123. If the implementation supports the POSIX shell option, the string
  124. stored in
  125. .IR buf
  126. after a call to:
  127. .sp
  128. .RS 4
  129. .nf
  130. confstr(_CS_PATH, buf, sizeof(buf))
  131. .fi
  132. .P
  133. .RE
  134. .P
  135. can be used as a value of the
  136. .IR PATH
  137. environment variable that accesses all of the standard utilities of
  138. POSIX.1\(hy2008, that are provided in a manner accessible via the
  139. .IR exec
  140. family of functions, if the return value is less than or equal to
  141. .IR sizeof (\c
  142. .IR buf ).
  143. .SH "RETURN VALUE"
  144. If
  145. .IR name
  146. has a configuration-defined value,
  147. \fIconfstr\fR()
  148. shall return the size of buffer that would be needed to hold the entire
  149. configuration-defined value including the terminating null. If this
  150. return value is greater than
  151. .IR len ,
  152. the string returned in
  153. .IR buf
  154. is truncated.
  155. .P
  156. If
  157. .IR name
  158. is invalid,
  159. \fIconfstr\fR()
  160. shall return 0 and set
  161. .IR errno
  162. to indicate the error.
  163. .P
  164. If
  165. .IR name
  166. does not have a configuration-defined value,
  167. \fIconfstr\fR()
  168. shall return 0 and leave
  169. .IR errno
  170. unchanged.
  171. .SH ERRORS
  172. The
  173. \fIconfstr\fR()
  174. function shall fail if:
  175. .TP
  176. .BR EINVAL
  177. The value of the
  178. .IR name
  179. argument is invalid.
  180. .LP
  181. .IR "The following sections are informative."
  182. .SH EXAMPLES
  183. None.
  184. .SH "APPLICATION USAGE"
  185. An application can distinguish between an invalid
  186. .IR name
  187. parameter value and one that corresponds to a configurable variable
  188. that has no configuration-defined value by checking if
  189. .IR errno
  190. is modified. This mirrors the behavior of
  191. \fIsysconf\fR().
  192. .P
  193. The original need for this function was to provide a way of finding the
  194. configuration-defined default value for the environment variable
  195. .IR PATH .
  196. Since
  197. .IR PATH
  198. can be modified by the user to include directories that could contain
  199. utilities replacing the standard utilities in the Shell and Utilities volume of POSIX.1\(hy2017, applications
  200. need a way to determine the system-supplied
  201. .IR PATH
  202. environment variable value that contains the correct search path for
  203. the standard utilities.
  204. .P
  205. An application could use:
  206. .sp
  207. .RS 4
  208. .nf
  209. confstr(name, (char *)NULL, (size_t)0)
  210. .fi
  211. .P
  212. .RE
  213. .P
  214. to find out how big a buffer is needed for the string value; use
  215. \fImalloc\fR()
  216. to allocate a buffer to hold the string; and call
  217. \fIconfstr\fR()
  218. again to get the string. Alternately, it could allocate a fixed, static
  219. buffer that is big enough to hold most answers (perhaps 512 or 1\|024
  220. bytes), but then use
  221. \fImalloc\fR()
  222. to allocate a larger buffer if it finds that this is too small.
  223. .SH RATIONALE
  224. Application developers can normally determine any configuration
  225. variable by means of reading from the stream opened by a call to:
  226. .sp
  227. .RS 4
  228. .nf
  229. popen("command -p getconf variable", "r");
  230. .fi
  231. .P
  232. .RE
  233. .P
  234. The
  235. \fIconfstr\fR()
  236. function with a
  237. .IR name
  238. argument of _CS_PATH returns a string that can be used as a
  239. .IR PATH
  240. environment variable setting that will reference the standard shell and
  241. utilities as described in the Shell and Utilities volume of POSIX.1\(hy2017.
  242. .P
  243. The
  244. \fIconfstr\fR()
  245. function copies the returned string into a buffer supplied by the
  246. application instead of returning a pointer to a string. This allows a
  247. cleaner function in some implementations (such as those with
  248. lightweight threads) and resolves questions about when the application
  249. must copy the string returned.
  250. .SH "FUTURE DIRECTIONS"
  251. None.
  252. .SH "SEE ALSO"
  253. .IR "\fIexec\fR\^",
  254. .IR "\fIfpathconf\fR\^(\|)",
  255. .IR "\fIsysconf\fR\^(\|)"
  256. .P
  257. The Base Definitions volume of POSIX.1\(hy2017,
  258. .IR "\fB<unistd.h>\fP"
  259. .P
  260. The Shell and Utilities volume of POSIX.1\(hy2017,
  261. .IR "\fIc99\fR\^"
  262. .\"
  263. .SH COPYRIGHT
  264. Portions of this text are reprinted and reproduced in electronic form
  265. from IEEE Std 1003.1-2017, Standard for Information Technology
  266. -- Portable Operating System Interface (POSIX), The Open Group Base
  267. Specifications Issue 7, 2018 Edition,
  268. Copyright (C) 2018 by the Institute of
  269. Electrical and Electronics Engineers, Inc and The Open Group.
  270. In the event of any discrepancy between this version and the original IEEE and
  271. The Open Group Standard, the original IEEE and The Open Group Standard
  272. is the referee document. The original Standard can be obtained online at
  273. http://www.opengroup.org/unix/online.html .
  274. .PP
  275. Any typographical or formatting errors that appear
  276. in this page are most likely
  277. to have been introduced during the conversion of the source files to
  278. man page format. To report such errors, see
  279. https://www.kernel.org/doc/man-pages/reporting_bugs.html .