libzahl

big integer library
git clone git://git.suckless.org/libzahl
Log | Files | Refs | README | 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)