.\" man page for Munts Technologies Linux Simple I/O Library
.\"
.\" Copyright (C)2016-2023, Philip Munts dba Munts Technologies.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions are met:
.\"
.\" * Redistributions of source code must retain the above copyright notice,
.\"   this list of conditions and the following disclaimer.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.TH libstream 2 "21 December 2018" "version 1" "Linux Simple I/O Library"
.SH NAME
.B libstream
\-\- Linux Simple I/O Library: Stream Framing Protocol Module
.SH SYNOPSIS
.nf
.B #include <libsimpleio/libstream.h>

.BI "typedef ssize_t (*" STREAM_readfn_t ")(int " fd ", void *" buf ", size_t " count ");"

.BI "typedef ssize_t (*" STREAM_writefn_t ")(int " fd ", const void *" buf ","
.BI "  size_t " count ");"

.BI "void STREAM_change_readfn(STREAM_readfn_t " newread ", int32_t *" error ");"

.BI "void STREAM_change_writefn(STREAM_writefn_t " newwrite ", int32_t *" error ");"

.BI "void STREAM_encode_frame(void *" src ", int32_t " srclen ", void *" dst ","
.BI "  int32_t " dstsize ", int32_t *" dstlen ", int32_t *" error ");"

.BI "void STREAM_decode_frame(void *" src ", int32_t " srclen ", void *" dst ","
.BI "  int32_t " dstsize ", int32_t *" dstlen ", int32_t *" error ");"

.BI "void STREAM_send_frame(int32_t " fd ", void *" buf ", int32_t " bufsize ","
.BI "  int32_t *" count ", int32_t *" error ");"

.BI "void STREAM_receive_frame(int32_t " fd ", void *" buf ", int32_t " bufsize ","
.BI "  int32_t *" framesize ", int32_t *" error ");"

.fi
Link with
.BR -lsimpleio .
.SH DESCRIPTION
.nh
These functions encode, decode, send, and receive frames to and from a
bidirectional byte stream, which will typically be either a serial port
or a network socket.  The frames are encoded according the the Stream
Framing Procotol.  See below for a link to the protocol specification.
.PP
All functions return either
.B 0
(upon success) or an
.B errno
value (upon failure) in
.IR *error .
.PP
.B STREAM_change_readfn()
changes the function used to read from the underlying stream from
the default
.B read()
to some other compatible function.
.PP
.B STREAM_change_writefn()
changes the function used to write to the underlying stream from
the default
.B write()
to some other compatible function.
.PP
.B STREAM_encode_frame()
encodes the message passed in
.IR *src ,
with its length passed in
.IR srclen .
Empty messages
.RI ( srclen ==0)
are allowed.
The encoded frame will be returned in
.IR *dst ,
whose maximum size must be passed in
.IR dstsize .
The size of the destination buffer must be at least 2 *
.IR srclen
+ 8 bytes.  The actual size of the encoded frame will be returned in
.IR *dstlen .
.PP
.B STREAM_decode_frame()
decodes the frame passed in
.IR *src ,
with its length passed in
.IR srclen .
The decoded message will be returned in
.IR *dst ,
whose maximum size must be passed in
.IR dstsize .
The actual size of the decoded message will be returned in
.IR *dstlen .
.PP
.B STREAM_send_frame()
writes an encoded frame to the bidirectional byte stream
indicated by the file descriptor
.IR fd .
The encoded frame is passed in
.IR buf " and"
its size is passed in
.IR bufsize .
Upon success, the number of bytes actually sent will be returned in
.IR *count .
.PP
.B STREAM_receive_frame()
reads one byte from the bidirectional byte stream indicated by
the file descriptor
.IR fd
and attempts to assemble a frame.  It should be called repeatedly
with the same
.IR *buf ,
.IR bufsize ,
and
.IR *framesize
parameters.  The
.IR *framesize
parameter is incremented for each byte received, and zeroed if an error
occurs.  The
.IR *error
parameter will be set to
.B EAGAIN
while a frame is being assembled. Upon successful assembly of a
complete frame, its size will be returned in
.IR *framesize
and zero returned in
.IR *error .
.SH SEE ALSO
.BR libsimpleio "(2), " libadc "(2), " libdac "(2), " libevent "(2), " libgpio "(2),"
.br
.BR libhidraw "(2), " libi2c "(2), " libipv4 "(2), " liblinux "(2), " liblinx "(2),"
.br
.BR libpwm "(2), " libserial "(2), " libspi "(2), " libwatchdog "(2)"
.PP
.B http://git.munts.com/libsimpleio/doc/StreamFramingProtocol.pdf
.SH AUTHOR
Philip Munts dba Munts Technologies.