.\" 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 <ipc.h>\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