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