zsave.3 - libzahl - big integer library
 (HTM) git clone git://git.suckless.org/libzahl
 (DIR) Log
 (DIR) Files
 (DIR) Refs
 (DIR) README
 (DIR) LICENSE
       ---
       zsave.3 (1177B)
       ---
            1 .TH ZSAVE 3 libzahl
            2 .SH NAME
            3 zsave - Marshal a big integer into a buffer
            4 .SH SYNOPSIS
            5 .nf
            6 #include <zahl.h>
            7 
            8 size_t zsave(z_t \fIa\fP, void *\fIbuf\fP);
            9 .fi
           10 .SH DESCRIPTION
           11 .B zsave
           12 marshals
           13 .I a
           14 into the buffer
           15 .IR buf
           16 unless
           17 .IR buf
           18 is
           19 .IR 0 .
           20 The data stored is not necessarily transferable
           21 between machines or between different versions
           22 of libzahl. For such use,
           23 use
           24 .BR zstr (3)
           25 instead.
           26 .P
           27 Upon successful completion,
           28 .I (*(int*)buf)
           29 will always be either -1, 0, or 1.
           30 .SH RETURN VALUE
           31 The number of bytes written to
           32 .IR buf ,
           33 or the number bytes that would have been written if
           34 .IR buf
           35 was not
           36 .IR 0 .
           37 .SH ERRORS
           38 This function cannot detect failure.
           39 .SH EXAMPLE
           40 .nf
           41 #include <zahl.h>
           42 #include <stdlib.h>
           43 
           44 int buffer_z(z_t num, char **buf, size_t *off) {
           45         size_t n = zsave(num, 0);
           46         char *new = realloc(*buf, *off + n);
           47         if (!new) {
           48                 return -1;
           49         }
           50         *buf = new;
           51         assert(zsave(num, *buf + *off) == n);
           52         *off += n;
           53         return 0;
           54 }
           55 .fi
           56 .SH RATIONALE
           57 This makes it possible to fork a process and send
           58 result between the parent and the child, as long as
           59 none of the process re-execute themself.
           60 .B zsave
           61 is much faster than
           62 .BR zstr (3).
           63 .SH SEE ALSO
           64 .BR zload (3),
           65 .BR zstr (3)