.Dd July 4, 2010 .Dt LIBBASE64 3 .Os NetBSD 1.4T .Sh NAME .Nm base64_e_r_cb , .Nm base64_e_w_cb , .Nm base64_d_r_cb , .Nm base64_d_w_cb , .Nm base64_r , .Nm base64_w , .Nm base64_close , .Nm base64_e_r_fwrap , .Nm base64_e_w_fwrap , .Nm base64_d_r_fwrap , .Nm base64_d_w_fwrap .Nd base-64 encoding/decoding .Sh SYNOPSIS .Fd #include .br .Nm cc .Op Ar arguments .Fl lbase64 .br .Ft void * .Fn base64_e_r_cb "void *cookie" "int (*cb)(void *, void *, int)" .Ft void * .Fn base64_e_w_cb "void *cookie" "int (*cb)(void *, const void *, int)" .Ft void * .Fn base64_d_r_cb "void *cookie" "int (*cb)(void *, void *, int)" .Ft void * .Fn base64_d_w_cb "void *cookie" "int (*cb)(void *, const void *, int)" .Ft int .Fn base64_r "void *handle" "void *buf" "int len" .Ft int .Fn base64_w "void *handle" "const void *buf" "int len" .Ft void .Fn base64_close "void *handle" .Ft FILE * .Fn base64_fwrap "FILE *fp" "unsigned int flags" .Sh DESCRIPTION These functions encode and decode data according to base-64 encoding rules (see RFC 4648). .Pp There are two styles of interface available, one that uses callbacks and one that uses stdio streams. The latter includes .Pa ; if this is undesirable, defining .Dv BASE64_NO_STDIO before including .Pa will suppress the stdio-based interfaces. .Pp The stdio interface is simpler but less general. When using this, you pass in a FILE pointer and a flags value. The FILE pointer refers to the stream from which you wish to read data to be processed (for a read stream) or to which you wish to write data once processed (for a write stream); the flags value specifies whether processing means encoding or decoding, whether you want a read stream or a write stream, and whether you want to close the underlying stream when the wrapper stream is closed. In any case, you then read (from a read stream) or write (to a write stream) to cause processing to take place. Closing the resulting stream terminates the operation (and flushes any buffered data, for write streams). .Pp The callback interface is philosophically similar, but avoiding stdio means the API is more complex. When creating a stream, you pass a cookie and a callback function; which function you call determines whether the result does base-64 encoding or decoding and whether it is a read-style stream (you call on it to provide processed data and it calls on the callback to obtain unprocessed data) or a write-style stream (you provide unprocessed data when you call on it; it returns processed data by calling the callback). Read-style callbacks are similar to .Xr read 2 except that the first argument is the cookie pointer provided when the stream was created rather than the file descriptor .Xr read 2 uses; write-style callbacks are akin to .Xr write 2 in much the same way. Like .Xr read 2 and .Xr write 2 , they return the number of bytes provided (for read-style) or accepted (for write-style), or a negative value on error; unlike .Xr read 2 and .Xr write 2 , though, there are no particular .Xr errno 2 semantics associated with error returns. .Pp Like .Xr read 2 , a zero return from a read-style interface means .Sq no more data . .Pp Unlike .Xr write 2 , write-style interfaces must accept all the data they are passed; any return other than an error (negative) return must equal the length value passed in. The library promises it will never call a write callback with a length value less than 1, and it is an error to call .Fn base64_w with such a length. .Pp .Fn base64_e_r_cb creates a read encoding callback stream. The arguments are a callback cookie and a read-style callback; the return value is a handle suitable for encoding data with base64_r and base64_close. .Pp .Fn base64_e_w_cb creates a write encoding callback stream. The arguments are a callback cookie and a write-style callback; the return value is a handle suitable for encoding data with base64_w and base64_close. .Pp .Fn base64_d_r_cb creates a read decoding callback stream. The arguments are a callback cookie and a read-style callback; the return value is a handle suitable for decoding data with base64_r and base64_close. .Pp .Fn base64_d_w_cb creates a write decoding callback stream. The arguments are a callback cookie and a write-style callback; the return value is a handle suitable for decoding data with base64_w and base64_close. .Pp .Fn base64_r reads from a read-style handle, performing encoding or decoding depending on how the handle was created. Using a write-style handle with this function always produces error returns. .Pp .Fn base64_w writes to a write-style handle, performing encoding or decoding depending on how the handle was created. Using a read-style handle with this function always produces error returns. .Pp .Fn base64_close closes a handle, freeing any associated data. For write handles, this also flushes any buffered data and writes any necessary trailing length markers; for read handles, any bytes returned by the underlying callback but not processed are discarded. .Pp .Fn base64_fwrap creates a stdio-style stream. The first argument is the stream to wrap, that is, the underlying stream from which unprocessed data are to be read or processed data are to be written; the second argument is a flags value, consisting of the bitwise OR of various bits. Exactly one of the .Dv BASE64_OP_ Ns No \&* values and exactly one of the .Dv BASE64_DIR_ Ns No \&* values must be specified. .Bl -tag -width XXX .It BASE64_OP_E Perform encoding. .It BASE64_OP_D Perform decoding. .It BASE64_DIR_R Perform read-style processing. .It BASE64_DIR_W Perform write-style processing. .It BASE64_CLOSE Close the underlying stream when the wrapped stream is closed (by default, this is not done). .El .Sh ERRORS Errors detected when creating a handle (or FILE stream) produce a nil pointer return. Errors detected within .Fn base64_r or .Fn base64_w produce a negative return value. .Sh BUGS There is no way to specify anything but the standard base64 encoding alphabet. .Pp There is no way to specify that padding is not used. .Sh AUTHOR der Mouse, .Aq mouse@rodents-montreal.org .