plan9fox/sys/man/2/proto

.TH PROTO 2
.SH NAME
rdproto \- parse and process a proto file listing
.SH SYNOPSIS
.nf
.ft L
#include <u.h>
#include <libc.h>
#include <disk.h>
.ft
.PP
.B
typedef void Protoenum(char *new, char *old, Dir *d, void *a)
.PP
.B
typedef void Protowarn(char *msg, void *a)
.PP
.B
int rdproto(char *proto, char *root, Protoenum *enm,
.br
.B
                         Protowarn *warn, void *a)
.SH DESCRIPTION
.I Rdproto
reads and interprets the named
.I proto
file relative to the 
root directory
.IR root .
.PP
Each line of the
.I proto
file specifies a file to copy except lines in the form of
.IB attr = val
which sets an attribute (see below).
Blank lines and lines beginning with
.B #
are ignored.
Indentation (usually tabs) is significant,
with each level of indentation corresponding to a level in the file tree.
Fields within a line are separated by white space.
The first field is the last path element in the destination file tree.
The second field specifies the permissions.
The third field is the owner of the file,
and the fourth is the group owning the file.
The fifth field is the name of the file from which to copy;
this file is read from the current name space,
not the source file tree.
All fields except the first are optional.
Specifying 
.B -
for permissions, owner, or group 
causes
.I rdproto
to fetch the corresponding information
from the file rather than override it.
(This is the default behavior when the fields
are not present; explicitly specifying
.B -
is useful when one wishes to set, say,
the file owner without setting the permissions.)
.PP
Names beginning with a
.L $
are expanded as environment variables.
If the first file specified in a directory is
.LR * ,
all of the files in that directory are considered listed.
If the first file is
.LR + ,
all of the files are copied, and all subdirectories
are recursively considered listed.
All files are considered relative to
.IR root .
.PP
Attributes, lines in the form of
.IB attr = val,
apply to all files in the current
indention level after the attribute line.
Attributes are inherited to deeper levels but
each level can override them individualy.
The attribute
.BI skip= regexp
skips all file names matching the regular expression
.I regexp
for
.B *
and
.B +
operations using
.IR regexp (2).
If owner or group is left unspecified on a file, the attributes
.BI uid= owner
and
.BI gid= group
will override these fields.
The
.BI mode= mode
attribute adds, sets or masks file permission bits if permissions
where not explicitly specified on the file. If multiple
.B mode=
lines are given and
.I mode
is not a set operation (forced by
.B !
character)
the modes are combined.
Except for the special
.B !
character,
.I mode
has the same syntax as in
.IR chmod (1).
.PP
For each file named by the
.IR proto ,
.I enm
is called with
.I new
pointing at the name of the file (without the root prefix),
.I old
pointing at the name of the source file (with the root prefix,
when applicable),
and
.I Dir
at the desired directory information for the new file.
Only the
.BR name ,
.BR uid ,
.BR gid ,
.BR mode ,
.BR mtime ,
and
.B length
fields are guaranteed to be valid.
The argument 
.I a
is the same argument passed to
.IR rdproto ;
typically it points at some extra state
used by the enumeration function.
.PP
When files or directories do not exist or 
cannot be read by 
.IR rdproto ,
it formats a warning message, calls 
.IR warn ,
and continues processing; 
if
.I warn
is nil, 
.I rdproto
prints the warning message to standard error.
.PP
.I Rdproto
returns zero
if
.I proto 
was processed, \-1 if it could not be opened.
.SH FILES
.TF /sys/lib/sysconfig/proto/portproto
.TP
.B /sys/lib/sysconfig/proto/
directory of prototype files.
.TP
.B /sys/lib/sysconfig/proto/portproto
generic prototype file.
.SH SOURCE
.B /sys/src/libdisk/proto.c
.SH SEE ALSO
.IR mk9660 (8),
.IR mkfs (8),
.IR regexp (2),
.IR chmod (1).