.\" man page for Munts Technologies Linux Simple I/O Library
.\"
.\" Copyright (C)2016-2024, 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 liblinux 2 "23 January 2024" "version 1" "Linux Simple I/O Library"
.SH NAME
.B liblinux
\-\- Linux Simple I/O Library: Linux System Call Wrapper Module
.SH SYNOPSIS
.nf
.B #include <libsimpleio/liblinux.h>

.BI "void LINUX_detach(int32_t *" error ");"

.BI "void LINUX_drop_privileges(const char *" username ", int32_t *" error ");"

.BI "void LINUX_openlog(const char *" id ", int32_t " options ", int32_t " facility ","
.BI "  int32_t *" error ");"

.BI "void LINUX_syslog(int32_t " priority ", const char *" msg ", int32_t *" error ");"

.BI "void LINUX_closelog(int32_t *" error ");"

.BI "int32_t LINUX_errno(void);"

.BI "void LINUX_strerror(int32_t " error ", char *" buf ", int32_t " bufsize ");"

.BI "void LINUX_poll(int32_t " numfiles ", int32_t *" files ", int32_t *" events ","
.BI "  int32_t *" results ", int32_t " timeout ", int32_t *" error ");"

.BI "void LINUX_usleep(int32_t " microseconds ", int32_t *" error ");"

.BI "void LINUX_command(const char *" cmd ", int32_t *" status ", int32_t *" error ");"

.BI "void LINUX_popen_read(const char *" cmd ", void **" stream ", int32_t *" error ");"

.BI "void LINUX_popen_write(const char *" cmd ", void **" stream ", int32_t *" error ");"

.BI "void LINUX_pclose(void *" stream ", int32_t *" error ");"

.BI "void *LINUX_indexpp(void **" p ", int32_t " i ");"

.BI "const char * const LINUX_model_name(void);

.fi
Link with
.BR -lsimpleio .
.SH DESCRIPTION
.nh
These functions wrap certain useful Linux system calls for use by other
programming languages such as Ada, C#, Free Pascal, and Go.  They are provided
for the convenience of devlopers using
.B libsimpleio
with those langauges.  For the C programming language, they offer no
particular benefit over the regular system call wrappers.
.PP
All functions return either
.B 0
(upon success) or an
.B errno
value (upon failure) in
.IR *error .
.PP
.B LINUX_detach()
detaches the calling process from its controlling terminal and continues
execution in the background.
.PP
.B LINUX_drop_privileges()
allows a process started by the superuser to drop its privileges to those
of the user specified by the
.I username
parameter.
.PP
.B LINUX_openlog()
opens a connection to the
.B syslog
message logger.  The
.IR options " and " facility
parameters accept the same values as the
.B openlog()
system library function.
.PP
.B LINUX_syslog()
transmits a text message supplied in the
.I msg
parameter to the
.B syslog
message logger. The
.I priority
parameter accepts the same values as the
.B syslog()
system library function.
.PP
.B LINUX_closelog()
closes the connection to the
.B syslog
message logger.
.PP
.B LINUX_errno()
returns the current value of the
.B errno
variable.
.PP
.B LINUX_strerror()
retrieves the error message for the
.B errno
value passed in the
.I error
parameter.  A destination buffer address and size must be passed in the
.IR buf " and " bufsize
parameters.
.PP
.B LINUX_poll()
waits for events on an set of file descriptors.  The number of file descriptors
is passed in the
.I numfiles
parameter.  An array of file descriptors is passed in the
.I files
parameter.  An array of requested events, using the same values as the
.B poll()
system library function, is passed in the
.I events
parameter.  The results for each file descriptor, also using the same values
as the
.B poll()
system library function, will be returned in the
.I results
parameter.  A timeout in milliseconds may be passed in the
.I timeout
parameter.  A timeout of zero indicates an immediate return without waiting at all.
A timeout of
.B -1
indicates waiting forever.  If the timeout expires without any
event on any file descriptor occurring, then
.I error
will be set to
.BR EAGAIN .
.PP
.B LINUX_usleep()
causes the calling program to sleep for the period indicated by
.IR microseconds ", by calling the"
.B usleep()
system library function.
.PP
.B LINUX_command()
passes the shell command string specified by the
.I cmd
parameter to the
.B system()
system library function for execution.  The return value from the
shell command will be returned in
.IR status "."
.PP
.B LINUX_popen_read()
opens a pipe for reading standard output from another program.  The shell command
string for running the program must be passed in the
.I cmd
parameter.  The
.B FILE
pointer for the pipe will be returned in the
.I stream
parameter.
.PP
.B LINUX_popen_read()
opens a pipe for writing standard input to another program.  The shell command
string for running the program must be passed in the
.I cmd
parameter.  The
.B FILE
pointer for the pipe will be returned in the
.I stream
parameter.
.PP
.B LINUX_pclose()
closes a pipe opened by
.B LINUX_popen_read()
or
.BR Linux_popen_close() .
The
.B FILE
pointer for the pipe must be passed in the
.I stream
parameter.
.PP
.B LINUX_indexpp()
is a helper function that indexes a C pointer to pointer(s).  It returns either
the selected element or
.B NULL
if the
.I p
parameter is
.B NULL
or if the
.I i
parameter
is less than zero.
.PP
.B LINUX_model_name()
returns the contents of
.B /proc/device-tree/model
or an empty string if that file cannot be read.
.SH SEE ALSO
.BR libsimpleio "(2), " libadc "(2), " libdac "(2), " libevent "(2), " libgpio "(2),"
.br
.BR libhidraw "(2), " libi2c "(2), " libipv4 "(2), " liblinx "(2), " libpwm "(2),"
.br
.BR libserial "(2), " libspi "(2), " libstream "(2), " libwatchdog "(2)"
.SH AUTHOR
Philip Munts dba Munts Technologies.