Validate unmarshalled state + add man pages for (un)marshal functions

Signed-off-by: Mattias Andrée <m@maandree.se>

1 files changed, 122 insertions, 0 deletions

diff --git a/libterminput_unmarshal_state.3 b/libterminput_unmarshal_state.3
new file mode 100644
index 0000000..dd498fa
--- /dev/null
+++ b/libterminput_unmarshal_state.3
@@ -0,0 +1,122 @@
+.TH LIBTERMINPUT_UNMARSHAL_STATE 3 LIBTERMINPUT
+.SH NAME
+libterminput_unmarshal_state \- Unmarshal the input parsing state
+.br
+libterminput_unmarshal_input \- Unmarshal the parsed input
+
+.SH SYNOPSIS
+.nf
+#include <libterminput.h>
+
+struct libterminput_unmarshaller {
+	int (*load)(struct libterminput_unmarshaller *\fIthis\fP, void *\fIdata\fP, size_t \fIsize\fP);
+	union {
+		void *ptr;
+		int i;
+		size_t zu;
+	} user;
+};
+
+int libterminput_unmarshal_state(struct libterminput_unmarshaller *\fIhow\fP, struct libterminput_state *\fIwhat\fP);
+int libterminput_unmarshal_input(struct libterminput_unmarshaller *\fIhow\fP, union libterminput_input *\fIwhat\fP);
+.fi
+.PP
+Link with
+.IR \-lterminput .
+
+.SH DESCRIPTION
+The
+.BR libterminput_unmarshal_state ()
+and
+.BR libterminput_unmarshal_input ()
+function unmarshals state into
+.I *what
+using
+.IR *how->load .
+.PP
+.I *how->load
+must return 0 on success and -1 on failure, and may set
+.I errno
+to indicate the error.
+.I how
+is fed back into
+.I *how->load
+(as
+.IR this )
+so that the
+.I *how->load
+function can use and modify
+.I how->user
+which contains application-defined data
+(typically a buffer, a file descriptor, or
+the size of the serialisation).
+.I data
+will be set to the output buffer for the data
+read by
+.I *how-load
+and
+.I size
+will be set to the number of bytes to read
+into from
+.IR data .
+
+.SH RETURN VALUE
+The
+.BR libterminput_unmarshal_state ()
+and
+.BR libterminput_unmarshal_input ()
+functions return 0 upon successful completion.
+On failure,
+.B -1
+is returnes, but
+.I errno
+remains unmodified, however any changes to
+.I errno
+by
+.I *how->load
+will remain.
+
+.SH ERRORS
+The
+.BR libterminput_unmarshal_state ()
+and
+.BR libterminput_unmarshal_input ()
+functions fail, without further modifying
+.IR errno ,
+if
+.I *how->load
+fails. The functions will also fail if:
+.TP
+.B EINVAL
+The read serialisation was invalid for the used
+version of the library (not a proper serialisation
+or containing data from a newer version of the
+library).
+
+.SH EXAMPLES
+None.
+
+.SH APPLICATION USAGE
+None.
+
+.SH RATIONALE
+None.
+
+.SH FUTURE DIRECTIONS
+None.
+
+.SH HISTORY
+The
+.BR libterminput_unmarshal_state ()
+and
+.BR libterminput_unmarshal_input ()
+functions were added in version 1.1 of libterminput.
+
+.SH NOTES
+None.
+
+.SH BUGS
+None.
+
+.SH SEE ALSO
+.BR libterminput_marshal_state (3)