first draft for man pages on ivy-c

1 files changed, 244 insertions, 0 deletions

diff --git a/doc/ivy-c.1 b/doc/ivy-c.1
new file mode 100644
index 0000000..00472e2
--- /dev/null
+++ b/doc/ivy-c.1
@@ -0,0 +1,244 @@
+'\"
+'\" Ivy, C interface \- library managing connexions to a software bus
+'\"
+'\" Copyright (C) 1997-1999
+'\" Centre d'Études de la Navigation Aérienne
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+'\" 
+'\"	# Start an argument description
+.de AP
+.ie !"\\$4"" .TP \\$4
+.el \{\
+.   ie !"\\$2"" .TP \\n()Cu
+.   el          .TP 15
+.\}
+.ie !"\\$3"" \{\
+.ta \\n()Au \\n()Bu
+\&\\$1	\\fI\\$2\\fP	(\\$3)
+.\".b
+.\}
+.el \{\
+.br
+.ie !"\\$2"" \{\
+\&\\$1	\\fI\\$2\\fP
+.\}
+.el \{\
+\&\\fI\\$1\\fP
+.\}
+.\}
+..
+'\"	# define tabbing values for .AP
+.de AS
+.nr )A 10n
+.if !"\\$1"" .nr )A \\w'\\$1'u+3n
+.nr )B \\n()Au+15n
+.\"
+.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
+.nr )C \\n()Bu+\\w'(in/out)'u+2n
+..
+'\"	# BS - start boxed text
+'\"	# ^y = starting y location
+'\"	# ^b = 1
+.TH Ivy-c 1 3.0  "Ivy-c Library Functions"
+.SH NAME
+IvyInit, IvyStart, IvyStop, IvyBindMsg, IvyUnbindMsg, IvyBindDirectMsg,
+IvySendMsg, IvySendDirectMsg, IvySendDieMsg, IvySendError, IvyGetApplicationName,
+IvyGetApplicationHost, IvyGetApplication, IvyGetApplicationList,
+IvyGetApplicationMessages, IvyDefaultApplicationCallback, IvyClasses,
+IvyChannelInit, IvyChannelSetUp, IvyMainLoop, IvyChannelClose,
+IvyChannelDelete, IvyChannelHandleRead,
+IvyChannelHandleExcpt,  IvyXtChannelInit, IvyXtChannelSetUp
+IvyXtChannelClose, IvyXtHandleChannelRead, IvyXtHandleChannelDelete,
+IvyXtChannelAppContext, 
+.SH SYNOPSIS
+useful library functions for communicating through a sofware bus
+.nf
+.sp
+\fBIvyInit(\fIAppName, ready, callback, data, die_callback, die_data\fB)\fR
+.sp
+void
+\fBIvyStart(\fIbus\fB)\fR
+.sp
+void
+\fBIvyStop()\fR
+.sp
+MsgRcvPtr
+\fBIvyBindMsg(\fIcallback, user_data, regexp, ...\fB)\fR
+.sp
+void
+\fBIvyUnbindMsg(\fIid\fB)\fR
+.sp
+void
+\fBIvyBindDirectMsg(\fIcallback, user_data\fB)\fR
+.sp
+int
+\fBIvySendMsg(\fIfmt_message, ...\fB)\fR
+.sp
+void
+\fBIvySendDirectMsg(\fIapp, id, msg\fB)\fR
+.sp
+void
+\fBIvySendDieMsg(\fIapp\fB)\fR
+.sp
+void
+\fBIvySendError(\fIapp, id, fmt, ...\fB)\fR
+.sp
+char*
+\fBIvyGetApplicationName(\fIapp\fB)\fR
+.sp
+char*
+\fBIvyGetApplicationHost(\fIapp\fB)\fR
+.sp
+char*
+\fBIvyGetApplication(\fIname\fB)\fR
+.sp
+char*
+\fBIvyGetApplicationList()\fR
+.sp
+char**
+\fBIvyGetApplicationMessages(\fapp\fB)\fR
+.sp
+char*
+\fBIvyDefaultApplicationCallback(\fIapp, user_data, Event\fB)\fR
+char*
+\fBIvyClasses(\fIargc, argv\fB)\fR
+.sp
+void
+\fBIvyChannelInit(\fIvoid\fB)\fR
+.sp
+Channel
+\fBIvyChannelSetUp(\fIfd, data, handle_delete, handle_read\fB)\fR
+.sp
+void
+\fBIvyMainLoop(\fIhook\fB)\fR
+.sp
+void
+\fBIvyChannelClose(\fIchannel\fB)\fR
+.sp
+static void
+\fBIvyChannelDelete(\fIchannel\fB)\fR
+.sp
+static void
+\fBIvyChannelHandleRead(\fIcurrent\fB)\fR
+.sp
+static void
+\fBIvyChannelHandleExcpt(\fIcurrent\fB)\fR
+.sp
+static void
+\fBIvyXtChannelInit(\fIvoid\fB)\fR
+.sp
+static void
+\fBIvyXtChannelSetUp(\fIfd, data, handle_delete, handle_read\fB)\fR
+.sp
+void
+\fBIvyXtChannelClose(\fIchannel\fB)\fR
+.sp
+static void
+\fBIvyXtHandleChannelRead(\fIclosure, source, id\fB)\fR
+.sp
+static void
+\fBIvyXtHandleChannelDelete(\fIclosure, source, id\fB)\fR
+.sp
+void
+\fBIvyChannelAppContext(\fIcntx\fB)\fR
+.SH ARGUMENTS
+.SH
+\fBIvyInit\fR:
+Initialisation of a connection
+.sp
+.AS "MaxSize" die_callback
+.AP const_char *AppName in
+Application Name
+.AP const_char *ready in
+Ready Message (can be NULL)
+.AP IvyApplicationCallback callback in
+Callback to be called on a connexion/deconnexion of an application
+.AP void *data in
+user data 
+.AP IvyDieCallback die_callback in
+last change callback before die
+.AP void *die_data in
+user data
+.SH
+\fBIvyStart\fR:
+Initialisation of TCP/UPD port and sending of a broadcast handshake on every network
+.AP const_char *bus in
+Bus (format : network list followed by broadcast port) example :
+123.231,123.123:2000 or 123.231 or :2000
+If no argument specified, check the environment variable \fBIVYBUS\fR, 
+else use the default value : 127.255.255.255:2010
+.SH 
+\fBIvyBindMsg\fR:
+Message binding
+.AP MsgCallback callback in
+.AP void *user_data in
+.AP const_char *regexp in
+.AP MsgRcvPtr id out
+.SH 
+\fBIvyUnbindMsg\fR:
+Message unbinding
+.AP MsgRcvPtr id in
+.SH
+\fBIvyChannelSetUp\fR:
+
+.AP HANDLE fd in
+.AP void *data in
+.AP ChannelHandleDelete handle_delete in
+.AP ChannelHandleRead handle_read in
+.AP Channel out out
+.VE 
+.BE
+.SH DESCRIPTION
+.PP
+These procedures provide facilities for connecting applications on a
+software bus and managing messages exchanges among them.
+
+.SH EXAMPLES
+Simple C code:
+.nf
+
+.DS
+
+#include "ivyloop.h"
+#include "ivysocket.h"
+#include "ivy.h"
+
+ int main (int argc, char* argv[]){
+	IvyInit ("IVYPROBE",
+		 bport,
+		 "IVYPROBE READY",
+		 ApplicationCallback,
+		 NULL,
+		 NULL,
+		 NULL)
+	IvyChannelSetUp(0, NULL, NULL, HandleStdin);
+	IvyStart (domains);
+	IvyMainLoop(0)
+};
+.DE
+
+.SH FILES
+.I /usr/include/ivy.h
+.I /usr/include/ivyloop.h
+.I /usr/include/ivysocket.h
+.SH ENVIRONMENT
+.I IVYDOMAINS
+.I IVYBUS
+.SH DIAGNOSTICS
+error messages displayed
+.SH BUGS
+none !
+.SH AUTHORS
+Francois-Regis Colin <fcolin@cenatoulouse.dgac.fr>
+Stephane Chatty <chatty@cenatoulouse.dgac.fr>
+.SH SEE ALSO
+ivyprobe (1)
+.sp
+For further details, please refer to the Ivy html page at http://www.cenatls.cena.dgac.fr/pii/produits/Ivy.html
+.SH NOTES
+In case of any comment or bug report on this library, please contact
+fcolin@cenatoulouse.dgac.fr, chatty@cenatoulouse.dgac.fr, jacomi@cenatoulouse.dgac.fr
+