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.