READF(2) READF(2)
NAME
readf, readfstr, createf, writef, writefstr, announcevol,
cmdoutput, tcmdoutput - Plan B convenience tools
SYNOPSIS
#include <u.h>
#include <libc.h>
#include <b.h>
void* readf(char* file, void* buf, long len, long* nout)
char* readfstr(char* file)
long writef(char* file, void* buf, long len)
long createf(char* file, void* buf, long len, ulong perm);
long writefstr(char* file, char* str)
int announcevol(int afd, char* addr, char* name, char* cnstr)
long cmdoutput(char* cmd, char* out, long sz);
long tcmdoutput(char* cmd, char* out, long sz);
DESCRIPTION
The first few functions provide a convenience interface to
perform entire file I/O and avoid keeping file descriptors
open for too long, which is important when using volumes
provided through bns(8). The last functions are convenience
routines used by many Plan B tools.
Readf reads all the contents of file into a memory buffer
and returns a pointer to it. For streams, only a single
read is made. The memory can be supplied by the caller, by
giving a non-nil buf and setting len to the size of the
buffer provided. When buf is nil, memory for the buffer is
allocated with malloc(2) and the caller is responsible for
calling free(2) to release it. If nout is not nil, the num-
ber of bytes read is placed in *nout.
Writef performs the opposite operation, and stores len bytes
starting at buf into file. The file must exist and have
write permission. It is legal to store zero bytes, to trun-
cate a file. Writef returns the number of bytes stored or a
negative value on errors.
Createf is like writef, but is creates the file when it does
not exist. The file mode is set to mode. When creating a
directory, the user supplied data is ignored.
Page 1 Plan 9 (printed 12/21/24)
READF(2) READF(2)
The functions readfstr and writefstr are convenience wrap-
pers that read and write files that do not contain null
characters. They provide a simpler interface for the common
case when the file contains text. Note that readfstr allo-
cates the memory used, and the caller is responsible for
releasing it. Also, readfstr returns a valid string for C or
nil on errors.
For files too big to have its size contained in a long inte-
ger, the functions described in read(2) must be used
instead.
The utility announcevol registers with adsrv(8) a Plan B
volume, to announce it and let other machines discover it.
Besides, it notifies the local bns(8) program to let it know
of the new local volume. The afd descriptor should be ini-
tially -1 or a connection to the relevant adsrv service. A
descriptor to talk to such program is returned when the vol-
ume could be registered. The user is expected to call
announcevol again, every few seconds or minutes, and supply
the descriptor being used to register the volume. The last
three parameters are the network address of the volume being
registered (where its 9P server can be reached), the global
name for the file tree, and the attributes of the tree as
described in cnstr(6).
The last two routines, cmdoutput and tcmdoutput, run cmd as
an rc(1) command line and place in out at most sz bytes
resulting from of standard output of the command. The number
of bytes read is the result of the function. The former uses
processes and the later is for use with thread(2).
SOURCE
/sys/src/libb
SEE ALSO
planb(1), intro(2), read(2)
DIAGNOSTICS
These functions set errstr. Readf and readfstr return nil
upon errors.
BUGS
The sizes should be 64 bit integers. For streams, readf
reads at most 16Kbytes each time it is called.
Page 2 Plan 9 (printed 12/21/24)