path: root/usr/src/lib/libast/common/man/ast.3

.fp 5 CW
.de Af
.ds ;G \\*(;G\\f\\$1\\$3\\f\\$2
.if !\\$4 .Af \\$2 \\$1 "\\$4" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
..
.de aF
.ie \\$3 .ft \\$1
.el \{\
.ds ;G \&
.nr ;G \\n(.f
.Af "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
\\*(;G
.ft \\n(;G \}
..
.de L
.aF 5 \\n(.f "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
..
.de LR
.aF 5 1 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
..
.de RL
.aF 1 5 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
..
.de EX		\" start example
.ta 1i 2i 3i 4i 5i 6i
.PP
.RS 
.PD 0
.ft 5
.nf
..
.de EE		\" end example
.fi
.ft
.PD
.RE
.PP
..
.TH AST 3
.SH NAME
ast \- miscellaneous libast support
.SH SYNOPSIS
.EX
#include <ast.h>

char*          astconf(const char* \fIname\fP, const char* \fIpath\fP, const char* \fIvalue\fP);
Ast_confdisc_t astconfdisc(Ast_confdisc_t new_notify);
void           astconflist(Sfio_t* stream, const char* path, int flags);
off_t          astcopy(int \fIrfd\fP, int \fIwfd\fP, off_t \fIn\fP);
int            astquery(int \fIfd\fP, const char* \fIformat\fP , ...);
.EE
.SH DESCRIPTION
.L astconf
is a string interface to the
.IR confstr (2),
.IR pathconf (2),
and
.IR sysconf (2)
calls.
If
.I value
is
.L 0
then the configuration parameter value for
.I name
is returned.
Some
.I name
configuration parameters may consult the
.I path
argument.
In this case if
.I path
is
.L 0
then
\f5"/"\fP
is used.
Otherwise if 
.I path
is not
.L 0
then it must exist.
The string return value for
.I name
remains unchanged until the next
.L astconf
call on
.IR name .
If
.I value
is
.L 0
then a valid string is always returned;
\f5""\fP
is returned if
.I name
has no configuration value.
This simplifies the programming interface:
.EX
if (!strcmp(astconf("PATH_RESOLVE", NiL, NiL), "logical"))
	/* the logical way ... */
.EE
If
.I value
is not
.L 0
then the configuration parameter value for
.I name
is set to
.IR value .
.L 0
is returned if the value cannot be set.
The paradigm is:
.EX
universe = astconf("UNIVERSE", 0, "att");
\|.\|.\|.
astconf("UNIVERSE", 0, universe);
.EE
The settable configuration names are:
.TP
.L FS_3D
.L 1
if
.IR 3d (1)
viewpathing is enabled,
.L 0
otherwise.
This is an alternative to the
.IR fs3d (3)
interface.
.TP
.L PATH_RESOLVE
.L logical
if symbolic links are followed during file tree traversal,
.L physical
if symbolic links are not followed during file tree traversal,
and
.L metaphysical
if symbolic links are followed at the top level during file tree traversal.
These correspond to the generic
.LR \-L ,
.LR \-P ,
and
.L \-H
command options.
.TP
.L UNIVERSE
.L ucb
for 
.I Berkeley
style and
.L att
otherwise.
This configuration parameter controls the
.I universe
setting on machines that support it (e.g., Pyramid).
.L UNIVERSE
also controls the behavior of some commands like
.IR cat (1)
and
.IR echo (1).
.PP
User defined
.I name
values may also be set and queried, but these should probably have
some form of vendor prefix to avoid being stomped by future standards.
.PP
.L astconfdisc
registers a discipline function
.EX
int (*notify)(const char* \fIname\fP, const char* \fIpath\fP, const char* \fIvalue\fP);
.EE
that is called just before the configuration parameter
.I name
is set to
.I value
relative to
.IR path .
If
.I notify
returns 
.L 0
then the configuration parameter value is not changed.
.PP
.L astconflist
lists the current configuration names and values of
.IR stream .
If
.I path
is
.L 0
then \f5"/"\fP is used where appropriate.
If
.I flags
is
.L 0
or
.L R_OK|W_OK
then all configuration parameters are listed.
.L R_OK
lists the readonly configuration parameters and 
.L W_OK
lists the settable configuration parameters.
.L X_OK
lists the settable configuration parameters in a form that can be
snarfed for input to the
.IR getconf (1)
command.
.PP
.L astcopy
efficiently copies up to
.I n
bytes from the file descriptor
.I rfd
to the file descriptor
.IR wfd .
The actual number of bytes copied is returned; \-1 is returned on error.
If
.I n
is  0 then an optimal number of bytes (with respect to both
.I rfd
and
.IR wfd )
is copied.
.PP
If possible
.IR mmap (2)
is used to do the transfer.
Some implementations may bypass user buffer copies usually required by the
.IR read (2)- write (2)
paradigm.
.PP
.L astquery
outputs an
.IR sfprintf (3)
prompt specified by
.I "format, .\|.\|."
to the controlling terminal and reads a response from the controlling terminal.
Offirmative response returns
.LR 0 ,
.L EOF
or quit response returns
.LR \-1 ,
otherwise
.L 1
is returned.
If
.I quit
is greater than
.L 0
then
.I exit(quit)
is called on a quit response.
The responses will eventually be locale specific.
.PP
.L astwinsize
returns the number of rows in
.I *rows
and the number of columns
.I *col
for the terminal file descriptor
.IR fd .
If the number of rows or columns cannot be determined or if
.I fd
is not a terminal then
.I *rows
and
.I *cols
are set to
.LR 0 .
If
.I ioctl (2)
methods fail then the environment variable
.L LINES
is used to set
.I *rows
and the environment variable
.L COLUMNS
is used to set
.IR *cols .
.SH "SEE ALSO"
getconf(1), confstr(2), mmap(2), pathconf(2), read(2), sysconf(2), write(2)