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. 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.