Obsolete
/
libipc-old
Archived
3
0
Fork 0
This repository has been archived on 2024-06-18. You can view files and clone it, but cannot push or open issues/pull-requests.
libipc-old/man/libipc.7

184 lines
4.4 KiB
Groff
Raw Normal View History

2020-12-08 22:49:12 +01:00
.\" 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