| blob | 8055be9dbc5e91432cd030ca28d9d9e900fb9c6f |
1 .fp 5 CW
2 .de Af
3 .ds ;G \\*(;G\\f\\$1\\$3\\f\\$2
5 ..
6 .de aF
8 .el \{\
9 .ds ;G \&
10 .nr ;G \\n(.f
11 .Af "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
12 \\*(;G
13 .ft \\n(;G \}
14 ..
15 .de L
16 .aF 5 \\n(.f "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
17 ..
18 .de LR
19 .aF 5 1 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
20 ..
21 .de RL
22 .aF 1 5 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
23 ..
24 .de EX \" start example
25 .ta 1i 2i 3i 4i 5i 6i
26 .PP
27 .RS
28 .PD 0
29 .ft 5
30 .nf
31 ..
32 .de EE \" end example
33 .fi
34 .ft
35 .PD
36 .RE
37 .PP
38 ..
39 .TH AST 3
40 .SH NAME
41 ast \- miscellaneous libast support
42 .SH SYNOPSIS
43 .EX
44 #include <ast.h>
46 char* astconf(const char* \fIname\fP, const char* \fIpath\fP, const char* \fIvalue\fP);
47 Ast_confdisc_t astconfdisc(Ast_confdisc_t new_notify);
48 void astconflist(Sfio_t* stream, const char* path, int flags);
49 off_t astcopy(int \fIrfd\fP, int \fIwfd\fP, off_t \fIn\fP);
50 int astquery(int \fIfd\fP, const char* \fIformat\fP , ...);
51 .EE
52 .SH DESCRIPTION
53 .L astconf
54 is a string interface to the
55 .IR confstr (2),
56 .IR pathconf (2),
57 and
58 .IR sysconf (2)
59 calls.
60 If
61 .I value
62 is
63 .L 0
64 then the configuration parameter value for
65 .I name
66 is returned.
67 Some
68 .I name
69 configuration parameters may consult the
70 .I path
71 argument.
72 In this case if
73 .I path
74 is
75 .L 0
76 then
77 \f5"/"\fP
78 is used.
79 Otherwise if
80 .I path
81 is not
82 .L 0
83 then it must exist.
84 The string return value for
85 .I name
86 remains unchanged until the next
87 .L astconf
88 call on
89 .IR name .
90 If
91 .I value
92 is
93 .L 0
94 then a valid string is always returned;
95 \f5""\fP
96 is returned if
97 .I name
98 has no configuration value.
99 This simplifies the programming interface:
100 .EX
101 if (!strcmp(astconf("PATH_RESOLVE", NiL, NiL), "logical"))
102 /* the logical way ... */
103 .EE
104 If
105 .I value
106 is not
107 .L 0
108 then the configuration parameter value for
109 .I name
110 is set to
111 .IR value .
112 .L 0
113 is returned if the value cannot be set.
114 The paradigm is:
115 .EX
116 universe = astconf("UNIVERSE", 0, "att");
117 \|.\|.\|.
118 astconf("UNIVERSE", 0, universe);
119 .EE
120 The settable configuration names are:
121 .TP
122 .L FS_3D
123 .L 1
124 if
125 .IR 3d (1)
126 viewpathing is enabled,
127 .L 0
128 otherwise.
129 This is an alternative to the
130 .IR fs3d (3)
131 interface.
132 .TP
133 .L PATH_RESOLVE
134 .L logical
135 if symbolic links are followed during file tree traversal,
136 .L physical
137 if symbolic links are not followed during file tree traversal,
138 and
139 .L metaphysical
140 if symbolic links are followed at the top level during file tree traversal.
141 These correspond to the generic
142 .LR \-L ,
143 .LR \-P ,
144 and
145 .L \-H
146 command options.
147 .TP
148 .L UNIVERSE
149 .L ucb
150 for
151 .I Berkeley
152 style and
153 .L att
154 otherwise.
155 This configuration parameter controls the
156 .I universe
157 setting on machines that support it (e.g., Pyramid).
158 .L UNIVERSE
159 also controls the behavior of some commands like
160 .IR cat (1)
161 and
162 .IR echo (1).
163 .PP
164 User defined
165 .I name
166 values may also be set and queried, but these should probably have
167 some form of vendor prefix to avoid being stomped by future standards.
168 .PP
169 .L astconfdisc
170 registers a discipline function
171 .EX
172 int (*notify)(const char* \fIname\fP, const char* \fIpath\fP, const char* \fIvalue\fP);
173 .EE
174 that is called just before the configuration parameter
175 .I name
176 is set to
177 .I value
178 relative to
179 .IR path .
180 If
181 .I notify
182 returns
183 .L 0
184 then the configuration parameter value is not changed.
185 .PP
186 .L astconflist
187 lists the current configuration names and values of
188 .IR stream .
189 If
190 .I path
191 is
192 .L 0
193 then \f5"/"\fP is used where appropriate.
194 If
195 .I flags
196 is
197 .L 0
198 or
199 .L R_OK|W_OK
200 then all configuration parameters are listed.
201 .L R_OK
202 lists the readonly configuration parameters and
203 .L W_OK
204 lists the settable configuration parameters.
205 .L X_OK
206 lists the settable configuration parameters in a form that can be
207 snarfed for input to the
208 .IR getconf (1)
209 command.
210 .PP
211 .L astcopy
212 efficiently copies up to
213 .I n
214 bytes from the file descriptor
215 .I rfd
216 to the file descriptor
217 .IR wfd .
218 The actual number of bytes copied is returned; \-1 is returned on error.
219 If
220 .I n
221 is 0 then an optimal number of bytes (with respect to both
222 .I rfd
223 and
224 .IR wfd )
225 is copied.
226 .PP
227 If possible
228 .IR mmap (2)
229 is used to do the transfer.
230 Some implementations may bypass user buffer copies usually required by the
231 .IR read (2)- write (2)
232 paradigm.
233 .PP
234 .L astquery
235 outputs an
236 .IR sfprintf (3)
237 prompt specified by
238 .I "format, .\|.\|."
239 to the controlling terminal and reads a response from the controlling terminal.
240 Offirmative response returns
241 .LR 0 ,
242 .L EOF
243 or quit response returns
244 .LR \-1 ,
245 otherwise
246 .L 1
247 is returned.
248 If
249 .I quit
250 is greater than
251 .L 0
252 then
253 .I exit(quit)
254 is called on a quit response.
255 The responses will eventually be locale specific.
256 .PP
257 .L astwinsize
258 returns the number of rows in
259 .I *rows
260 and the number of columns
261 .I *col
262 for the terminal file descriptor
263 .IR fd .
264 If the number of rows or columns cannot be determined or if
265 .I fd
266 is not a terminal then
267 .I *rows
268 and
269 .I *cols
270 are set to
271 .LR 0 .
272 If
273 .I ioctl (2)
274 methods fail then the environment variable
275 .L LINES
276 is used to set
277 .I *rows
278 and the environment variable
279 .L COLUMNS
280 is used to set
281 .IR *cols .
282 .SH "SEE ALSO"
283 getconf(1), confstr(2), mmap(2), pathconf(2), read(2), sysconf(2), write(2)