Commit | Line | Data |
---|---|---|
cc009182 KB |
1 | .\" Copyright (c) 1993 The Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
4 | .\" %sccs.include.redist.roff% | |
5 | .\" | |
6 | .\" @(#)confstr.3 5.1 (Berkeley) %G% | |
7 | .\" | |
8 | .Dd | |
9 | .Dt CONFSTR 3 | |
10 | .Os BSD 4 | |
11 | .Sh NAME | |
12 | .Nm confstr | |
13 | .Nd get string-valued configurable variables | |
14 | .Sh SYNOPSIS | |
15 | .Fd #include <unistd.h> | |
16 | .Ft size_t | |
17 | .Fn confstr "int name" "char *buf" "size_t len" | |
18 | .Sh DESCRIPTION | |
19 | .Bf -symbolic | |
20 | This interface is obsoleted by sysctl(3). | |
21 | .Ef | |
22 | .Pp | |
23 | The | |
24 | .Fn confstr | |
25 | function provides a method for applications to get configuration | |
26 | defined string values. | |
27 | .Pp | |
28 | The | |
29 | .Fa name | |
30 | argument specifies the system variable to be queried. | |
31 | Symbolic constants for each name value are found in the include file | |
32 | .Li <unistd.h> . | |
33 | The | |
34 | .Fa len | |
35 | argument specifies the size of the buffer referenced by the | |
36 | argument | |
37 | .Fa buf . | |
38 | If | |
39 | .Fa len | |
40 | is non-zero, | |
41 | .Fa buf | |
42 | is a non-null pointer, and | |
43 | .Fa name | |
44 | has a value, up to | |
45 | .Fa len | |
46 | \- 1 bytes of the value are copied into the buffer | |
47 | .Fa buf . | |
48 | The copied value is always null terminated. | |
49 | .Pp | |
50 | The available values are as follows: | |
51 | .Pp | |
52 | .Bl -tag -width "123456" | |
53 | .Pp | |
54 | .It Li _CS_PATH | |
55 | Return a value for the | |
56 | .Ev PATH | |
57 | environment variable that finds all the standard utilities. | |
58 | .El | |
59 | .Sh RETURN VALUES | |
60 | If the call to | |
61 | .Nm confstr | |
62 | is not successful, \-1 is returned and | |
63 | .Va errno | |
64 | is set appropriately. | |
65 | Otherwise, if the variable does not have a configuration defined value, | |
66 | 0 is returned and | |
67 | .Va errno | |
68 | is not modified. | |
69 | Otherwise, the buffer size needed to hold the entire configuration-defined | |
70 | value is returned. | |
71 | If this size is greater than the argument | |
72 | .Fa len , | |
73 | the string in | |
74 | .Fa buf | |
75 | was truncated. | |
76 | .Sh ERRORS | |
77 | The | |
78 | .Nm confstr | |
79 | function may fail and set | |
80 | .Va error | |
81 | for any of the errors specified for the library functions | |
82 | .Xr malloc 3 | |
83 | and | |
84 | .Xr sysctl 3 . | |
85 | .Pp | |
86 | In addition, the following errors may be reported: | |
87 | .Bl -tag -width Er | |
88 | .It Bq Er EINVAL | |
89 | The value of the | |
90 | .Fa name | |
91 | argument is invalid. | |
92 | .Sh SEE ALSO | |
93 | .Xr sysctl 3 | |
94 | .Sh HISTORY | |
95 | The | |
96 | .Nm confstr | |
97 | function first appeared in 4.4BSD. |