| blob | 002c0c5f2a41adef382929ca0a26c463f8e81ec6 |
1 .\"
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved.
44 .\" Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved.
45 .\"
46 .TH CONFSTR 3C "Dec 15, 2003"
47 .SH NAME
48 confstr \- get configurable variables
49 .SH SYNOPSIS
50 .LP
51 .nf
52 #include <unistd.h>
54 \fBsize_t\fR \fBconfstr\fR(\fBint\fR \fIname\fR, \fBchar *\fR\fIbuf\fR, \fBsize_t\fR \fIlen\fR);
55 .fi
57 .SH DESCRIPTION
58 .sp
59 .LP
60 The \fBconfstr()\fR function provides a method for applications to get
61 configuration-defined string values. Its use and purpose are similar to the
62 \fBsysconf\fR(3C) function, but it is used where string values rather than
63 numeric values are returned.
64 .sp
65 .LP
66 The \fIname\fR argument represents the system variable to be queried.
67 .sp
68 .LP
69 If \fIlen\fR is not \fB0\fR, and if \fIname\fR has a configuration-defined
70 value, \fBconfstr()\fR copies that value into the \fIlen\fR-byte buffer
71 pointed to by \fIbuf\fR. If the string to be returned is longer than \fIlen\fR
72 bytes, including the terminating null, then \fBconfstr()\fR truncates the
73 string to \fIlen\fR\(mi1 bytes and null-terminates the result. The application
74 can detect that the string was truncated by comparing the value returned by
75 \fBconfstr()\fR with \fIlen\fR.
76 .sp
77 .LP
78 If \fIlen\fR is \fB0\fR, \fBconfstr()\fR still returns the integer value as
79 defined below, but does not return the string.
80 .sp
81 .LP
82 The \fBconfstr()\fR function supports the following values for \fIname\fR,
83 defined in \fB<unistd.h>\fR, for both SPARC and x86:
84 .sp
85 .ne 2
86 .na
87 \fB\fB_CS_PATH\fR\fR
88 .ad
89 .sp .6
90 .RS 4n
91 If the ISO POSIX.2 standard is supported, this is the value for the \fBPATH\fR
92 environment variable that finds all standard utilities. Otherwise the meaning
93 of this value is unspecified.
94 .RE
96 .sp
97 .ne 2
98 .na
99 \fB\fB_CS_POSIX_V6_ILP32_OFF32_CFLAGS\fR\fR
100 .ad
101 .sp .6
102 .RS 4n
103 If \fBsysconf\fR(\fB_SC_V6_ILP32_OFF32\fR) returns -1, the meaning of this
104 value is unspecified. Otherwise, this value is the set of initial options to
105 be given to the \fBc99\fR utility to build an application using a programming
106 model with 32-bit \fBint\fR, \fBlong\fR, \fBpointer\fR, and \fBoff_t\fR types.
107 .RE
109 .sp
110 .ne 2
111 .na
112 \fB\fB_CS_POSIX_V6_ILP32_OFF32_LDFLAGS\fR\fR
113 .ad
114 .sp .6
115 .RS 4n
116 If \fBsysconf\fR(\fB_SC_V6_ILP32_OFF32\fR) returns -1, the meaning of this
117 value is unspecified. Otherwise, this value is the set of final options to be
118 given to the \fBc99\fR utility to build an application using a programming
119 model with 32-bit \fBint\fR, \fBlong\fR, \fBpointer\fR, and \fBoff_t\fR types.
120 .RE
122 .sp
123 .ne 2
124 .na
125 \fB\fB_CS_POSIX_V6_ILP32_OFF32_LIBS\fR\fR
126 .ad
127 .sp .6
128 .RS 4n
129 If \fBsysconf\fR(\fB_SC_V6_ILP32_OFF32\fR) returns -1, the meaning of this
130 value is unspecified. Otherwise, this value is the set of libraries to be given
131 to the \fBc99\fR utility to build an application using a programming model with
132 32-bit \fBint\fR, \fBlong\fR, \fBpointer\fR, and \fBoff_t\fR types.
133 .RE
135 .sp
136 .ne 2
137 .na
138 \fB\fB_CS_POSIX_V6_ILP32_OFFBIG_CFLAGS\fR\fR
139 .ad
140 .sp .6
141 .RS 4n
142 If \fBsysconf\fR(\fB_SC_V6_ILP32_OFFBIG\fR) returns -1, the meaning of this
143 value is unspecified. Otherwise, this value is the set of initial options to be
144 given to the \fBc99\fR utility to build an application using a programming
145 model with 32-bit \fBint\fR, \fBlong\fR, and \fBpointer\fR types, and an
146 \fBoff_t\fR type using at least 64 bits.
147 .RE
149 .sp
150 .ne 2
151 .na
152 \fB\fB_CS_POSIX_V6_ILP32_OFFBIG_LDFLAGS\fR\fR
153 .ad
154 .sp .6
155 .RS 4n
156 If \fBsysconf\fR(\fB_SC_V6_ILP32_OFFBIG\fR) returns -1, the meaning of this
157 value is unspecified. Otherwise, this value is the set of final options to be
158 given to the \fBc99\fR utility to build an application using a programming
159 model with 32-bit \fBint\fR, \fBlong\fR, and \fBpointer\fR types, and an
160 \fBoff_t\fR type using at least 64 bits.
161 .RE
163 .sp
164 .ne 2
165 .na
166 \fB\fB_CS_POSIX_V6_ILP32_OFFBIG_LIBS\fR\fR
167 .ad
168 .sp .6
169 .RS 4n
170 If \fBsysconf\fR(\fB_SC_V6_ILP32_OFFBIG\fR) returns -1, the meaning of this
171 value is unspecified. Otherwise, this value is the set of libraries to be given
172 to the \fBc99\fR utility to build an application using a programming model with
173 32-bit \fBint\fR, \fBlong\fR, and \fBpointer\fR types, and an \fBoff_t\fR type
174 using at least 64 bits.
175 .RE
177 .sp
178 .ne 2
179 .na
180 \fB\fB_CS_POSIX_V6_LP64_OFF64_CFLAGS\fR\fR
181 .ad
182 .sp .6
183 .RS 4n
184 If \fBsysconf\fR(\fB_SC_V6_LP64_OFF64\fR) returns -1, the meaning of this value
185 is unspecified. Otherwise, this value is the set of initial options to be given
186 to the \fBc99\fR utility to build an application using a programming model with
187 64-bit \fBint\fR, \fBlong\fR, \fBpointer\fR, and \fBoff_t\fR types.
188 .RE
190 .sp
191 .ne 2
192 .na
193 \fB\fB_CS_POSIX_V6_LP64_OFF64_LDFLAGS\fR\fR
194 .ad
195 .sp .6
196 .RS 4n
197 If \fBsysconf\fR(\fB_SC_V6_LP64_OFF64\fR) returns -1, the meaning of this value
198 is unspecified. Otherwise, this value is the set of final options to be given
199 to the \fBc99\fR utility to build an application using a programming model with
200 64-bit \fBint\fR, \fBlong\fR, \fBpointer\fR, and \fBoff_t\fR types.
201 .RE
203 .sp
204 .ne 2
205 .na
206 \fB\fB_CS_POSIX_V6_LP64_OFF64_LIBS\fR\fR
207 .ad
208 .sp .6
209 .RS 4n
210 If \fBsysconf\fR(\fB_SC_V6_LP64_OFF64\fR) returns -1, the meaning of this value
211 is unspecified. Otherwise, this value is the set of libraries to be given to
212 the \fBc99\fR utility to build an application using a programming model with
213 64-bit \fBint\fR, \fBlong\fR, \fBpointer\fR, and \fBoff_t\fR types.
214 .RE
216 .sp
217 .ne 2
218 .na
219 \fB\fB_CS_POSIX_V6_LPBIG_OFFBIG_CFLAGS\fR\fR
220 .ad
221 .sp .6
222 .RS 4n
223 If \fBsysconf\fR(\fB_SC_V6_LPBIG_OFFBIG\fR) returns -1, the meaning of this
224 value is unspecified. Otherwise, this value is the set of initial options to be
225 given to the \fBc99\fR utility to build an application using a programming
226 model with an \fBint\fR type using at least 32 bits and \fBlong\fR,
227 \fBpointer\fR, and \fBoff_t\fR types using at least 64 bits.
228 .RE
230 .sp
231 .ne 2
232 .na
233 \fB\fB_CS_POSIX_V6_LPBIG_OFFBIG_LDFLAGS\fR\fR
234 .ad
235 .sp .6
236 .RS 4n
237 If \fBsysconf\fR(\fB_SC_V6_LPBIG_OFFBIG\fR) returns -1, the meaning of this
238 value is unspecified. Otherwise, this value is the set of final options to be
239 given to the \fBc99\fR utility to build an application using a programming
240 model with an \fBint\fR type using at least 32 bits and \fBlong\fR,
241 \fBpointer\fR, and \fBoff_t\fR types using at least 64 bits.
242 .RE
244 .sp
245 .ne 2
246 .na
247 \fB\fB_CS_POSIX_V6_LPBIG_OFFBIG_LIBS\fR\fR
248 .ad
249 .sp .6
250 .RS 4n
251 If \fBsysconf\fR(\fB_SC_V6_LPBIG_OFFBIG\fR) returns -1, the meaning of this
252 value is unspecified. Otherwise, this value is the set of libraries to be given
253 to the \fBc99\fR utility to build an application using a programming model with
254 an \fBint\fR type using at least 32 bits and \fBlong\fR, \fBpointer\fR, and
255 \fBoff_t\fR types using at least 64 bits.
256 .RE
258 .sp
259 .ne 2
260 .na
261 \fB\fB_CS_POSIX_V6_WIDTH_RESTRICTED_ENVS\fR\fR
262 .ad
263 .sp .6
264 .RS 4n
265 This value is a <newline>-separated list of names of programming environments
266 supported by the implementation in which the widths of the \fBblksize_t\fR,
267 \fBcc_t\fR, \fBmode_t\fR, \fBnfds_t\fR, \fBpid_t\fR, \fBptrdiff_t\fR,
268 \fBsize_t\fR, \fBspeed_t\fR, \fBssize_t\fR, \fBsuseconds_t\fR, \fBtcflag_t\fR,
269 \fBuseconds_t\fR, \fBwchar_t\fR, and \fBwint_t\fR types are no greater than the
270 width of type \fBlong\fR.
271 .RE
273 .sp
274 .ne 2
275 .na
276 \fB\fB_CS_XBS5_ILP32_OFF32_CFLAGS\fR\fR
277 .ad
278 .sp .6
279 .RS 4n
280 If \fBsysconf(_SC_XBS5_ILP32_OFF32)\fR returns \(mi1 the meaning of this value
281 is unspecified. Otherwise, this value is the set of initial options to be
282 given to the \fBcc\fR and \fBc89\fR utilities to build an application using a
283 programming model with 32-bit \fBint\fR, \fBlong\fR, \fBpointer\fR, and
284 \fBoff_t\fR types.
285 .RE
287 .sp
288 .ne 2
289 .na
290 \fB\fB_CS_XBS5_ILP32_OFF32_LDFLAGS\fR\fR
291 .ad
292 .sp .6
293 .RS 4n
294 If \fBsysconf(_SC_XBS5_ILP32_OFF32)\fR returns \(mi1 the meaning of this value
295 is unspecified. Otherwise, this value is the set of final options to be given
296 to the \fBcc\fR and \fBc89\fR utilities to build an application using a
297 programming model with 32-bit \fBint\fR, \fBlong\fR, \fBpointer\fR, and
298 \fBoff_t\fR types.
299 .RE
301 .sp
302 .ne 2
303 .na
304 \fB\fB_CS_XBS5_ILP32_OFF32_LIBS\fR\fR
305 .ad
306 .sp .6
307 .RS 4n
308 If \fBsysconf(_SC_XBS5_ILP32_OFF32)\fR returns \(mi1 the meaning of this value
309 is unspecified. Otherwise, this value is the set of libraries to be given to
310 the \fBcc\fR and \fBc89\fR utilities to build an application using a
311 programming model with 32-bit \fBint\fR, \fBlong\fR, \fBpointer\fR, and
312 \fBoff_t\fR types.
313 .RE
315 .sp
316 .ne 2
317 .na
318 \fB\fB_CS_XBS5_ILP32_OFF32_LINTFLAGS\fR\fR
319 .ad
320 .sp .6
321 .RS 4n
322 If \fBsysconf(_SC_XBS5_ILP32_OFF32)\fR returns \(mi1 the meaning of this value
323 is unspecified. Otherwise, this value is the set of options to be given to the
324 \fBlint\fR utility to check application source using a programming model with
325 32-bit \fBint\fR, \fBlong\fR, \fBpointer\fR, and \fBoff_t\fR types.
326 .RE
328 .sp
329 .ne 2
330 .na
331 \fB\fB_CS_XBS5_ILP32_OFFBIG_CFLAGS\fR\fR
332 .ad
333 .sp .6
334 .RS 4n
335 If \fBsysconf(_SC_XBS5_ILP32_OFFBIG)\fR returns \(mi1 the meaning of this value
336 is unspecified. Otherwise, this value is the set of initial options to be
337 given to the \fBcc\fR and \fBc89\fR utilities to build an application using a
338 programming model with 32-bit \fBint\fR, \fBlong\fR, and \fBpointer\fR types,
339 and an \fBoff_t\fR type using at least 64 bits.
340 .RE
342 .sp
343 .ne 2
344 .na
345 \fB\fB_CS_XBS5_ILP32_OFFBIG_LDFLAGS\fR\fR
346 .ad
347 .sp .6
348 .RS 4n
349 If \fBsysconf(SC_XBS5_ILP32_OFFBIG)\fR returns \(mi1 the meaning of this value
350 is unspecified. Otherwise, this value is the set of final options to be given
351 to the \fBcc\fR and \fBc89\fR utilities to build an application using a
352 programming model with 32-bit \fBint\fR, \fBlong\fR, and \fBpointer\fR types,
353 and an \fBoff_t\fR type using at least 64 bits.
354 .RE
356 .sp
357 .ne 2
358 .na
359 \fB\fB_CS_XBS5_ILP32_OFFBIG_LIBS\fR\fR
360 .ad
361 .sp .6
362 .RS 4n
363 If \fBsysconf(_SC_XBS5_ILP32_OFFBIG)\fR returns \(mi1 the meaning of this value
364 is unspecified. Otherwise, this value is the set of libraries to be given to
365 the \fBcc\fR and \fBc89\fR utilities to build an application using a
366 programming model with 32-bit \fBint\fR, \fBlong\fR, and \fBpointer\fR types,
367 and an \fBoff_t\fR type using at least 64 bits.
368 .RE
370 .sp
371 .ne 2
372 .na
373 \fB\fB_CS_XBS5_ILP32_OFFBIG_LINTFLAGS\fR\fR
374 .ad
375 .sp .6
376 .RS 4n
377 If \fBsysconf(_SC_XBS5_ILP32_OFFBIG)\fR returns \(mi1 the meaning of this value
378 is unspecified. Otherwise, this value is the set of options to be given to the
379 \fBlint\fR utility to check an application using a programming model with
380 32-bit \fBint\fR, \fBlong\fR, and \fBpointer\fR types, and an \fBoff_t\fR type
381 using at least 64 bits.
382 .RE
384 .sp
385 .LP
386 The \fBconfstr()\fR function supports the following values for \fIname\fR,
387 defined in \fB<unistd.h>\fR, for SPARC only:
388 .sp
389 .ne 2
390 .na
391 \fB\fB_CS_XBS5_LP64_OFF64_CFLAGS\fR\fR
392 .ad
393 .sp .6
394 .RS 4n
395 If \fBsysconf(_SC_XBS5_LP64_OFF64)\fR returns \(mi1 the meaning of this value
396 is unspecified. Otherwise, this value is the set of initial options to be
397 given to the \fBcc\fR and \fBc89\fR utilities to build an application using a
398 programming model with 64-bit \fBint\fR, \fBlong\fR, \fBpointer\fR, and
399 \fBoff_t\fR types.
400 .RE
402 .sp
403 .ne 2
404 .na
405 \fB\fB_CS_XBS5_LP64_OFF64_LDFLAGS\fR\fR
406 .ad
407 .sp .6
408 .RS 4n
409 If \fBsysconf(_SC_XBS5_LP64_OFF64)\fR returns \(mi1 the meaning of this value
410 is unspecified. Otherwise, this value is the set of final options to be given
411 to the \fBcc\fR and \fBc89\fR utilities to build an application using a
412 programming model with 64-bit \fBint\fR, \fBlong\fR, \fBpointer\fR, and
413 \fBoff_t\fR types.
414 .RE
416 .sp
417 .ne 2
418 .na
419 \fB\fB_CS_XBS5_LP64_OFF64_LIBS\fR\fR
420 .ad
421 .sp .6
422 .RS 4n
423 If \fBsysconf(_SC_XBS5_LP64_OFF64)\fR returns \(mi1 the meaning of this value
424 is unspecified. Otherwise, this value is the set of libraries to be given to
425 the \fBcc\fR and \fBc89\fR utilities to build an application using a
426 programming model with 64-bit \fBint\fR, \fBlong\fR, \fBpointer\fR, and
427 \fBoff_t\fR types.
428 .RE
430 .sp
431 .ne 2
432 .na
433 \fB\fB_CS_XBS5_LP64_OFF64_LINTFLAGS\fR\fR
434 .ad
435 .sp .6
436 .RS 4n
437 If \fBsysconf(_SC_XBS5_LP64_OFF64)\fR returns \(mi1 the meaning of this value
438 is unspecified. Otherwise, this value is the set of options to be given to the
439 \fBlint\fR utility to check application source using a programming model with
440 64-bit \fBint\fR, \fBlong\fR, \fBpointer\fR, and \fBoff_t\fR types.
441 .RE
443 .sp
444 .ne 2
445 .na
446 \fB\fB_CS_XBS5_LPBIG_OFFBIG_CFLAGS\fR\fR
447 .ad
448 .sp .6
449 .RS 4n
450 If \fBsysconf(_SC_XBS5_LPBIG_OFFBIG)\fR returns \(mi1 the meaning of this value
451 is unspecified. Otherwise, this value is the set of initial options to be
452 given to the \fBcc\fR and \fBc89\fR utilities to build an application using a
453 programming model with an \fBint\fR type using at least 32 bits and \fBlong\fR,
454 \fBpointer\fR, and \fBoff_t\fR types using at least 64 bits.
455 .RE
457 .sp
458 .ne 2
459 .na
460 \fB\fB_CS_XBS5_LPBIG_OFFBIG_LDFLAGS\fR\fR
461 .ad
462 .sp .6
463 .RS 4n
464 If \fBsysconf(_SC_XBS5_LPBIG_OFFBIG)\fR returns \(mi1 the meaning of this value
465 is unspecified. Otherwise, this value is the set of final options to be given
466 to the \fBcc\fR and \fBc89\fR utilities to build an application using a
467 programming model with an \fBint\fR type using at least 32 bits and \fBlong\fR,
468 \fBpointer\fR, and \fBoff_t\fR types using at least 64 bits.
469 .RE
471 .sp
472 .ne 2
473 .na
474 \fB\fB_CS_XBS5_LPBIG_OFFBIG_LIBS\fR\fR
475 .ad
476 .sp .6
477 .RS 4n
478 If \fBsysconf(_SC_XBS5_LPBIG_OFFBIG)\fR returns \(mi1 the meaning of this value
479 is unspecified. Otherwise, this value is the set of libraries to be given to
480 the \fBcc\fR and \fBc89\fR utilities to build an application using a
481 programming model with an \fBint\fR type using at least 32 bits and \fBlong\fR,
482 \fBpointer\fR, and \fBoff_t\fR types using at least 64 bits.
483 .RE
485 .sp
486 .ne 2
487 .na
488 \fB\fB_CS_XBS5_LPBIG_OFFBIG_LINTFLAGS\fR\fR
489 .ad
490 .sp .6
491 .RS 4n
492 If \fBsysconf(_SC_XBS5_LPBIG_OFFBIG)\fR returns \(mi1 the meaning of this value
493 is unspecified. Otherwise, this value is the set of options to be given to the
494 \fBlint\fR utility to check application source using a programming model with
495 an \fBint\fR type using at least 32 bits and \fBlong\fR, \fBpointer\fR, and
496 \fBoff_t\fR types using at least 64 bits.
497 .RE
499 .SH RETURN VALUES
500 .sp
501 .LP
502 If \fIname\fR has a configuration-defined value, the \fBconfstr()\fR function
503 returns the size of buffer that would be needed to hold the entire
504 configuration-defined value. If this return value is greater than \fIlen\fR,
505 the string returned in \fIbuf\fR is truncated.
506 .sp
507 .LP
508 If \fIname\fR is invalid, \fBconfstr()\fR returns \fB0\fR and sets \fBerrno\fR
509 to indicate the error.
510 .sp
511 .LP
512 If \fIname\fR does not have a configuration-defined value, \fBconfstr()\fR
513 returns \fB0\fR and leaves \fBerrno\fR unchanged.
514 .SH ERRORS
515 .sp
516 .LP
517 The \fBconfstr()\fR function will fail if:
518 .sp
519 .ne 2
520 .na
521 \fB\fBEINVAL\fR\fR
522 .ad
523 .RS 10n
524 The value of the \fIname\fR argument is invalid.
525 .RE
527 .SH ATTRIBUTES
528 .sp
529 .LP
530 See \fBattributes\fR(5) for descriptions of the following attributes:
531 .sp
533 .sp
534 .TS
535 box;
536 c | c
537 l | l .
538 ATTRIBUTE TYPE ATTRIBUTE VALUE
539 _
540 Interface Stability Standard
541 _
542 MT-Level Mt-Safe
543 .TE
545 .SH SEE ALSO
546 .sp
547 .LP
548 \fBpathconf\fR(2), \fBsysconf\fR(3C), \fBattributes\fR(5), \fBlfcompile\fR(5),
549 \fBlfcompile64\fR(5), \fBstandards\fR(5)