diff --git a/Makefile b/Makefile index 980ca4e..6e9bd63 100644 --- a/Makefile +++ b/Makefile @@ -39,9 +39,9 @@ src/ipc.h.uninstall: @echo ' RM > $(INCLUDEDIR)/ipc.h' $(Q)rm -f '$(DESTDIR)$(INCLUDEDIR)/ipc.h' -man/libipc.7: man/libipc.7.md man +man/libipc.7: man/libipc.7.scd man @echo ' MAN > man/libipc.7' - $(Q)pandoc -s --from markdown --to man 'man/libipc.7.md' -o 'man/libipc.7' + $(Q)scdoc < 'man/libipc.7.scd' > 'man/libipc.7' man/libipc.7.install: man/libipc.7 @@ -127,7 +127,7 @@ src/error.o.clean: src/error.o.uninstall: -src/logger.o: src/logger.c src/logger.h +src/logger.o: src/logger.c src/logger.h src/ipc.h @echo ' CC > src/logger.o' $(Q)$(CC) $(CFLAGS) -fPIC -std=c11 -c src/logger.c -fPIC -std=c11 -o src/logger.o @@ -242,7 +242,7 @@ $(PACKAGE)-$(VERSION).tar.gz: distdir $(PACKAGE)-$(VERSION)/Makefile \ $(PACKAGE)-$(VERSION)/project.zsh \ $(PACKAGE)-$(VERSION)/src/ipc.h \ - $(PACKAGE)-$(VERSION)/man/libipc.7.md \ + $(PACKAGE)-$(VERSION)/man/libipc.7.scd \ $(PACKAGE)-$(VERSION)/src/communication.c \ $(PACKAGE)-$(VERSION)/src/error.c \ $(PACKAGE)-$(VERSION)/src/logger.c \ @@ -262,7 +262,7 @@ $(PACKAGE)-$(VERSION).tar.xz: distdir $(PACKAGE)-$(VERSION)/Makefile \ $(PACKAGE)-$(VERSION)/project.zsh \ $(PACKAGE)-$(VERSION)/src/ipc.h \ - $(PACKAGE)-$(VERSION)/man/libipc.7.md \ + $(PACKAGE)-$(VERSION)/man/libipc.7.scd \ $(PACKAGE)-$(VERSION)/src/communication.c \ $(PACKAGE)-$(VERSION)/src/error.c \ $(PACKAGE)-$(VERSION)/src/logger.c \ @@ -282,7 +282,7 @@ $(PACKAGE)-$(VERSION).tar.bz2: distdir $(PACKAGE)-$(VERSION)/Makefile \ $(PACKAGE)-$(VERSION)/project.zsh \ $(PACKAGE)-$(VERSION)/src/ipc.h \ - $(PACKAGE)-$(VERSION)/man/libipc.7.md \ + $(PACKAGE)-$(VERSION)/man/libipc.7.scd \ $(PACKAGE)-$(VERSION)/src/communication.c \ $(PACKAGE)-$(VERSION)/src/error.c \ $(PACKAGE)-$(VERSION)/src/logger.c \ @@ -321,7 +321,7 @@ help: @echo 'Project targets: ' @echo ' - libipc  library' @echo ' - src/ipc.h  header' - @echo ' - man/libipc.7  man' + @echo ' - man/libipc.7  scdocman' @echo '' @echo 'Makefile options:' @echo ' - gnu: false' diff --git a/man/libipc.7.md b/man/libipc.7.md deleted file mode 100644 index 6114e57..0000000 --- a/man/libipc.7.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -title: libipc -header: libipc Manual -footer: libipc -date: 2018-11-20 -section: 7 -... - -# NAME - -libipc - Simple, easy-to-use IPC library - -# DESCRIPTION - -**libipc** is a library that provides interprocess communication medium between applications. -It provides both client and server code. - -# SYNOPSIS - -**`#include `** - -## Initialization, exchanges, disconnection - -// server initialization\ -*enum ipc_errors* **ipc_server_init** (*char* \*\*env , *struct ipc_connection_info* \*srv, *const char* \*sname);\ -// connection establishement to a server\ -*enum ipc_errors* **ipc_connection** (*char* \*\*env, *struct ipc_connection_info* \*, *const char* \*);\ - -// closing a server\ -*enum ipc_errors* **ipc_server_close** (*struct ipc_connection_info* \*srv);\ -// closing a connection\ -*enum ipc_errors* **ipc_close** (*struct ipc_connection_info* \*p);\ -*enum ipc_errors* **ipc_accept** (*struct ipc_connection_info* \*srv, *struct ipc_connection_info* \*p); - -*enum ipc_errors* **ipc_read** (*const struct ipc_connection_info* \*, *struct ipc_message* \*m);\ -*enum ipc_errors* **ipc_write** (*const struct ipc_connection_info* \*, *const struct ipc_message* \*m);\ -*enum ipc_errors* **ipc_wait_event** (*struct ipc_connection_infos* \*clients, *struct ipc_connection_info* \*srv, *struct ipc_event* \*event); - - -// store and remove only pointers on allocated structures\ -*enum ipc_errors* **ipc_add** (*struct ipc_connection_infos* \*cinfos, *struct ipc_connection_info* \*cinfo);\ -*enum ipc_errors* **ipc_del** (*struct ipc_connection_infos* \*cinfos, *struct ipc_connection_info* \*cinfo); - -// add an arbitrary file descriptor to read\ -*enum ipc_errors* **ipc_add_fd** (*struct ipc_connection_infos* \*cinfos, *int* fd); - - -## Message functions - -// create msg structure from buffer\ -*enum ipc_errors* **ipc_message_format_read** (*struct ipc_message* \*m, *const char* \*buf, *ssize_t* msize);\ -// create buffer from msg structure\ -*enum ipc_errors* **ipc_message_format_write** (*const struct ipc_message* \*m, *char* \*\*buf, *ssize_t* \*msize);\ - -*enum ipc_errors* **ipc_message_format** (*struct ipc_message* \*m, *char* type, *const char* \*payload, *ssize_t* length);\ -*enum ipc_errors* **ipc_message_format_data** (*struct ipc_message* \*m, *const char* \*payload, *ssize_t* length);\ -*enum ipc_errors* **ipc_message_format_server_close** (*struct ipc_message* \*m);\ - -*enum ipc_errors* **ipc_message_empty** (*struct ipc_message* \*m); - - -# STRUCTURES - - 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_connection_infos { - 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 - }; - - -# ENUMERATIONS - - enum msg_types { - MSG_TYPE_SERVER_CLOSE = 0 - , MSG_TYPE_ERR - , MSG_TYPE_DATA - } message_types; - -Function **ipc_wait_event** returns an *event type* structure.\ -The event may be a (dis)connection, received data or an error.\ -It also can be *IPC_EVENT_TYPE_EXTRA_SOCKET* since an arbitrary file descriptor can be added to the *ipc_connection_infos* structure with **ipc_add_fd**. - - 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 { - ... - }; - - -# EXAMPLES - -Examples are available in the */examples* directory. - -# NOTES - -# SEE ALSO - -# BUGS & LIMITATIONS - - - Documentation is currently limited. - - Rerouting IPC connexions through other services (for example, through a network bridge service) is currently not possible. - diff --git a/man/libipc.7.scd b/man/libipc.7.scd new file mode 100644 index 0000000..7cdb2b6 --- /dev/null +++ b/man/libipc.7.scd @@ -0,0 +1,140 @@ +libipc(7) + +# NAME + +libipc - Simple, easy-to-use IPC library + +# DESCRIPTION + +**libipc** is a library that provides interprocess communication medium between applications. +It provides both client and server code. + +# SYNOPSIS + +**#include ** + +## Initialization, exchanges, disconnection + +// server initialization + +_enum ipc_errors_ **ipc_server_init** (*char* \*\*env , *struct ipc_connection_info* \*srv, *const char* \*sname); + +// connection establishement to a server + +_enum ipc_errors_ **ipc_connection** (*char* \*\*env, *struct ipc_connection_info* \*, *const char* \*); + +// closing a server + +_enum ipc_errors_ **ipc_server_close** (*struct ipc_connection_info* \*srv); + +// closing a connection + +_enum ipc_errors_ **ipc_close** (*struct ipc_connection_info* \*p);++ +_enum ipc_errors_ **ipc_accept** (*struct ipc_connection_info* \*srv, *struct ipc_connection_info* \*p); + +_enum ipc_errors_ **ipc_read** (*const struct ipc_connection_info* \*, *struct ipc_message* \*m);++ +_enum ipc_errors_ **ipc_write** (*const struct ipc_connection_info* \*, *const struct ipc_message* \*m);++ +_enum ipc_errors_ **ipc_wait_event** (*struct ipc_connection_infos* \*clients, *struct ipc_connection_info* \*srv, *struct ipc_event* \*event); + + +// store and remove only pointers on allocated structures + +_enum ipc_errors_ **ipc_add** (*struct ipc_connection_infos* \*cinfos, *struct ipc_connection_info* \*cinfo);++ +_enum ipc_errors_ **ipc_del** (*struct ipc_connection_infos* \*cinfos, *struct ipc_connection_info* \*cinfo); + +// add an arbitrary file descriptor to read + +_enum ipc_errors_ **ipc_add_fd** (*struct ipc_connection_infos* \*cinfos, *int* fd); + + +## Message functions + +// create msg structure from buffer + +_enum ipc_errors_ **ipc_message_format_read** (*struct ipc_message* \*m, *const char* \*buf, *ssize_t* msize); + +// create buffer from msg structure + +_enum ipc_errors_ **ipc_message_format_write** (*const struct ipc_message* \*m, *char* \*\*buf, *ssize_t* \*msize); + +_enum ipc_errors_ **ipc_message_format** (*struct ipc_message* \*m, *char* type, *const char* \*payload, *ssize_t* length);++ +_enum ipc_errors_ **ipc_message_format_data** (*struct ipc_message* \*m, *const char* \*payload, *ssize_t* length);++ +_enum ipc_errors_ **ipc_message_format_server_close** (*struct ipc_message* \*m); + +_enum ipc_errors_ **ipc_message_empty** (*struct ipc_message* \*m); + + +# STRUCTURES + +``` + 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_connection_infos { + 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 + }; +``` + + +# ENUMERATIONS + +``` + enum msg_types { + MSG_TYPE_SERVER_CLOSE = 0 + , MSG_TYPE_ERR + , MSG_TYPE_DATA + } message_types; +``` + +Function **ipc_wait_event** returns an *event type* structure.\ +The event may be a (dis)connection, received data or an error.\ +It also can be *IPC_EVENT_TYPE_EXTRA_SOCKET* since an arbitrary file descriptor can be added to the *ipc_connection_infos* structure with **ipc_add_fd**. + +``` + 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 { + ... + }; +``` + + +# EXAMPLES + +Examples are available in the */examples* directory. + +# NOTES + +# SEE ALSO + +# BUGS & LIMITATIONS + +- Documentation is currently limited. +- Tests are currently limited. +- No code audit has been made. + diff --git a/project.zsh b/project.zsh index 918d376..0c336e1 100644 --- a/project.zsh +++ b/project.zsh @@ -12,7 +12,7 @@ cflags[libipc]="-std=c11" type[src/ipc.h]=header -type[man/libipc.7]=man +type[man/libipc.7]=scdocman -dist=(Makefile project.zsh src/ipc.h man/*.md) +dist=(Makefile project.zsh src/ipc.h man/*.scd)