VENTI-PACKET(2)                                   VENTI-PACKET(2)

     NAME
          Packet, packetalloc, packetappend, packetasize, packetcmp,
          packetconcat, packetconsume, packetcopy, packetdup,
          packetforeign, packetfragments, packetfree, packetheader,
          packetpeek, packetprefix, packetsha1, packetsize,
          packetsplit, packetstats, packettrailer, packettrim - zero-
          copy network buffers

     SYNOPSIS
          #include <u.h>
          #include <libc.h>
          #include <venti.h>

          Packet* packetalloc(void);

          void    packetappend(Packet *p, uchar *buf, int n)

          uint    packetasize(Packet *p)

          int     packetcmp(Packet *p, Packet *q)

          void    packetconcat(Packet *p, Packet *q)

          int     packetconsume(Packet *p, uchar *buf, int n)

          int     packetcopy(Packet *p, uchar *buf, int offset, int n)

          Packet* packetdup(Packet *p, int offset, int n)

          Packet* packetforeign(uchar *buf, int n,
                      void (*free)(void *a), void *a)

          int     packetfragments(Packet *p, IOchunk *io, int nio,
                      int offset)

          void    packetfree(Packet *p)

          uchar*  packetheader(Packet *p, int n)

          uchar*  packetpeek(Packet *p, uchar *buf, int offset, int n)

          void    packetprefix(Packet *p, uchar *buf, int n)

          void    packetsha1(Packet *p, uchar sha1[20])

          uint    packetsize(Packet *p)

          Packet* packetsplit(Packet *p, int n)

          void    packetstats(void)

     Page 1                       Plan 9             (printed 3/19/24)

     VENTI-PACKET(2)                                   VENTI-PACKET(2)

          uchar*  packettrailer(Packet *p, int n)

          int     packettrim(Packet *p, int offset, int n)

     DESCRIPTION
          A Packet is a chain of blocks of data.  Each block, called a
          fragment, is contiguous in memory, but the entire packet may
          not be.  This representation helps avoid unnecessary memory
          copies.

          Packetalloc allocates an empty packet.

          Packetappend appends the n bytes at buf to the end of p.

          Packetasize returns the number of data bytes allocated to p.
          This may be larger than the number of bytes stored in p
          because fragments may not be filled completely.

          Packetcmp compares the data sections of two packets as
          memcmp (see memory(2)) would.

          Packetconcat removes all data from q, appending it to p.

          Packetconsume removes n bytes from the beginning of p, stor-
          ing them into buf.

          Packetcopy copies n bytes at offset in p to buf.

          Packetdup creates a new packet initialized with n bytes from
          offset in p.

          Packetforeign allocates a packet containing `foreign' data:
          the n bytes pointed to by buf. Once the bytes are no longer
          needed, they are freed by calling free(a).

          Packetfragments initializes up to nio of the io structures
          with pointers to the data in p, starting at offset. It
          returns the total number of bytes represented by the
          returned structures.  Packetfragments initializes any unused
          io structures with nil pointer and zero length.

          Packetfree frees the packet p.

          Packetheader returns a pointer to the first n bytes of p,
          making them contiguous in memory if necessary.

          Packetpeek returns a pointer to the n bytes at offset in p.
          If the requested bytes are already stored contiguously in
          memory, the returned pointer points at the internal data
          storage for p. Otherwise, the bytes are copied into buf, and
          packetpeek returns buf.

     Page 2                       Plan 9             (printed 3/19/24)

     VENTI-PACKET(2)                                   VENTI-PACKET(2)

          Packetprefix inserts a copy of the n bytes at buf at the
          beginning of p.

          Packetsha1 computes the SHA1 hash of the data contained in
          p.

          Packetsize returns the length, in bytes, of the data con-
          tained in p.

          Packetsplit returns a new packet initialized with n bytes
          removed from the beginning of p.

          Packetstats prints run-time statistics to standard output.

          Packettrailer returns a pointer to the last n bytes of p,
          making them contiguous in memory if necessary.

          Packettrim deletes all bytes from the packet p except the n
          bytes at offset offset.

     SOURCE
          /sys/src/libventi

     SEE ALSO
          venti(2)

     DIAGNOSTICS
          These functions return errors only when passed invalid
          inputs, e.g., requests for data at negative offsets or
          beyond the end of a packet.

          Functions returning pointers return nil on error; functions
          returning integers return -1 on error.  Most functions
          returning integers return 0 on success.  The exceptions are
          packetfragments and packetcmp, whose return values are
          described above.

          When these functions run out of memory, they print error
          messages and call sysfatal.

     Page 3                       Plan 9             (printed 3/19/24)