xref: /minix3/lib/libc/gen/confstr.3 (revision 2fe8fb192fe7e8720e3e7a77f928da545e872a6a)
1.\"	$NetBSD: confstr.3,v 1.20 2010/04/22 08:00:34 jruoho Exp $
2.\"
3.\" Copyright (c) 1993
4.\"	The Regents of the University of California.  All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\" 3. Neither the name of the University nor the names of its contributors
15.\"    may be used to endorse or promote products derived from this software
16.\"    without specific prior written permission.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28.\" SUCH DAMAGE.
29.\"
30.\"	@(#)confstr.3	8.1 (Berkeley) 6/4/93
31.\"
32.Dd April 22, 2010
33.Dt CONFSTR 3
34.Os
35.Sh NAME
36.Nm confstr
37.Nd get string-valued configurable variables
38.Sh LIBRARY
39.Lb libc
40.Sh SYNOPSIS
41.In unistd.h
42.Ft size_t
43.Fn confstr "int name" "char *buf" "size_t len"
44.Sh DESCRIPTION
45.Bf -symbolic
46This interface is obsoleted by
47.Xr sysctl 3 .
48.Ef
49.Pp
50The
51.Fn confstr
52function provides a method for applications to get configuration
53defined string values.
54.Pp
55The
56.Fa name
57argument specifies the system variable to be queried.
58Symbolic constants for each name value are found in the
59.In unistd.h
60header.
61The
62.Fa len
63argument specifies the size of the buffer referenced by the
64argument
65.Fa buf .
66If
67.Fa len
68is non-zero,
69.Fa buf
70is a non-null pointer, and
71.Fa name
72has a value, up to
73.Fa len
74\- 1 bytes of the value are copied into the buffer
75.Fa buf .
76The copied value is always null terminated.
77.Pp
78The available values are as follows:
79.Pp
80.Bl -tag -width "123456"
81.It Li _CS_PATH
82Return a value for the
83.Ev PATH
84environment variable that finds all the standard utilities.
85.El
86.Sh RETURN VALUES
87If the call to
88.Nm confstr
89is not successful, 0 is returned and
90.Va errno
91is set appropriately.
92Otherwise, if the variable does not have a configuration defined value,
930 is returned and
94.Va errno
95is not modified.
96Otherwise, the buffer size needed to hold the entire configuration-defined
97value is returned.
98If this size is greater than the argument
99.Fa len ,
100the string in
101.Fa buf
102was truncated.
103.Sh ERRORS
104The
105.Nm confstr
106function may fail and set
107.Va error
108for any of the errors specified for the library functions
109.Xr malloc 3
110and
111.Xr sysctl 3 .
112.Pp
113In addition, the following errors may be reported:
114.Bl -tag -width Er
115.It Bq Er EINVAL
116The value of the
117.Fa name
118argument is invalid.
119.El
120.Sh SEE ALSO
121.Xr sysctl 3
122.Sh STANDARDS
123The
124.Nm confstr
125function conforms to
126.St -p1003.2-92 .
127.Sh HISTORY
128The
129.Nm confstr
130function first appeared in
131.Bx 4.4 .
132.Sh BUGS
133The standards require us to return 0 both on errors, and when the value
134is not set.
135