184 lines
4.4 KiB
Groff
184 lines
4.4 KiB
Groff
.\" 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
|