From 7cb5d2669c8327e486e7f858ef42dc479b1fdf3e Mon Sep 17 00:00:00 2001 From: Karchnu Date: Tue, 8 Dec 2020 22:49:12 +0100 Subject: [PATCH] Man page added. --- man/libipc.7 | 183 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 183 insertions(+) create mode 100644 man/libipc.7 diff --git a/man/libipc.7 b/man/libipc.7 new file mode 100644 index 0000000..0ac03e7 --- /dev/null +++ b/man/libipc.7 @@ -0,0 +1,183 @@ +.\" Generated by scdoc 1.9.6 +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.nh +.ad l +.\" Begin generated content: +.TH "libipc" "7" "2020-12-08" +.P +.SH NAME +.P +libipc - Simple, easy-to-use IPC library +.P +.SH DESCRIPTION +.P +\fB\fRlibipc\fB\fR is a library that provides interprocess communication medium between applications. +It provides both client and server code. +.P +.SH SYNOPSIS +.P +\fB\fR#include \fB\fR +.P +.SS Initialization, exchanges, disconnection +.P +// server initialization +.P +\fIenum ipc_errors\fR \fB\fRipc_server_init\fB\fR (\fBchar\fR **env, \fBconst char\fR *sname); +.P +// connection establishement to a server +.P +\fIenum ipc_errors\fR \fB\fRipc_connection\fB\fR (\fBchar\fR **env, \fBconst char\fR *, int *serverfd); +.P +// closing a server +.P +\fIenum ipc_errors\fR \fB\fRipc_close\fB\fR (\fBstruct ipc_connection_info\fR *srv); +.P +// closing a connection +.P +\fIenum ipc_errors\fR \fB\fRipc_close\fB\fR (\fBstruct ipc_connection_info\fR *p); +.br +\fIenum ipc_errors\fR \fB\fRipc_accept\fB\fR (\fBstruct ipc_connection_info\fR *srv, \fBstruct ipc_connection_info\fR *p); +.P +\fIenum ipc_errors\fR \fB\fRipc_read\fB\fR (\fBconst struct ipc_connection_info\fR *, \fBstruct ipc_message\fR *m); +.br +\fIenum ipc_errors\fR \fB\fRipc_write\fB\fR (\fBconst struct ipc_connection_info\fR *, \fBconst struct ipc_message\fR *m); +.br +\fIenum ipc_errors\fR \fB\fRipc_wait_event\fB\fR (\fBstruct ipc_ctx\fR *clients, \fBstruct ipc_connection_info\fR *srv, \fBstruct ipc_event\fR *event); +.P +.P +// store and remove only pointers on allocated structures +.P +\fIenum ipc_errors\fR \fB\fRipc_add\fB\fR (\fBstruct ipc_ctx\fR *cinfos, \fBstruct ipc_connection_info\fR *cinfo); +.br +\fIenum ipc_errors\fR \fB\fRipc_del\fB\fR (\fBstruct ipc_ctx\fR *cinfos, \fBstruct ipc_connection_info\fR *cinfo); +.P +// add an arbitrary file descriptor to read +.P +\fIenum ipc_errors\fR \fB\fRipc_add_fd\fB\fR (\fBstruct ipc_ctx\fR *cinfos, \fBint\fR fd); +.P +.P +.SS Message functions +.P +// create msg structure from buffer +.P +\fIenum ipc_errors\fR \fB\fRipc_message_format_read\fB\fR (\fBstruct ipc_message\fR *m, \fBconst char\fR *buf, \fBssize_t\fR msize); +.P +// create buffer from msg structure +.P +\fIenum ipc_errors\fR \fB\fRipc_message_format_write\fB\fR (\fBconst struct ipc_message\fR *m, \fBchar\fR **buf, \fBssize_t\fR *msize); +.P +\fIenum ipc_errors\fR \fB\fRipc_message_format\fB\fR (\fBstruct ipc_message\fR *m, \fBchar\fR type, \fBconst char\fR *payload, \fBssize_t\fR length); +.br +\fIenum ipc_errors\fR \fB\fRipc_message_format_data\fB\fR (\fBstruct ipc_message\fR *m, \fBconst char\fR *payload, \fBssize_t\fR length); +.br +\fIenum ipc_errors\fR \fB\fRipc_message_format_server_close\fB\fR (\fBstruct ipc_message\fR *m); +.P +\fIenum ipc_errors\fR \fB\fRipc_message_empty\fB\fR (\fBstruct ipc_message\fR *m); +.P +.P +.SH STRUCTURES +.P +.nf +.RS 4 + struct ipc_connection_info { + uint32_t version; + uint32_t index; + int32_t fd; + char type; // may be an arbitrary fd + char *spath; // max size: PATH_MAX, used to store unix socket path + }; + + struct ipc_ctx { + struct ipc_connection_info ** cinfos; + int32_t size; + }; + + struct ipc_message { + char type; + uint32_t length; + char *payload; + }; + + struct ipc_event { + enum ipc_event_type type; + void* origin; // currently used as an client or service pointer + void* m; // message pointer + }; +.fi +.RE +.P +.P +.SH ENUMERATIONS +.P +.nf +.RS 4 + enum msg_types { + MSG_TYPE_SERVER_CLOSE = 0 + , MSG_TYPE_ERR + , MSG_TYPE_DATA + } message_types; +.fi +.RE +.P +Function \fB\fRipc_wait_event\fB\fR returns an \fBevent type\fR structure. +The event may be a (dis)connection, received data or an error. +It also can be \fBIPC_EVENT_TYPE_EXTRA_SOCKET\fR since an arbitrary file descriptor can be added to the \fBipc_ctx\fR structure with \fB\fRipc_add_fd\fB\fR. +.P +.nf +.RS 4 + enum ipc_event_type { + IPC_EVENT_TYPE_NOT_SET + , IPC_EVENT_TYPE_ERROR + , IPC_EVENT_TYPE_EXTRA_SOCKET + , IPC_EVENT_TYPE_CONNECTION + , IPC_EVENT_TYPE_DISCONNECTION + , IPC_EVENT_TYPE_MESSAGE + }; + + enum ipc_errors { + \&.\&.\&. + }; +.fi +.RE +.P +.P +.SH EXAMPLES +.P +Examples are available in the \fB/examples\fR directory. +.P +.SH NOTES +.P +.SH SEE ALSO +.P +.SH BUGS & LIMITATIONS +.P +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.IP \(bu 4 +.\} +Documentation is currently limited. +.RE +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.IP \(bu 4 +.\} +Tests are currently limited. +.RE +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.IP \(bu 4 +.\} +No code audit has been made. + +.RE +.P