Add man pages for the libcpg functions.

git-svn-id: http://svn.fedorahosted.org/svn/corosync/trunk@940 fd59a12c-fef9-0310-b244-a6a79926bd2f

man/Makefile

@@ -45,6 +45,17 @@ html:
 	groff -mandoc -Thtml evs_mcast_groups.3 > html/evs_mcast_groups.html
 	groff -mandoc -Thtml evs_mcast_joined.3 > html/evs_mcast_joined.html
 	groff -mandoc -Thtml evs_membership_get.3 > html/evs_membership_get.html
+
+	groff -mandoc -Thtml cpg_overview.8 > html/cpg_overview.html
+	groff -mandoc -Thtml cpg_initialize.3 > html/cpg_initialize.html
+	groff -mandoc -Thtml cpg_finalize.3 > html/cpg_finalize.html
+	groff -mandoc -Thtml cpg_fd_get.3 > html/cpg_fd_get.html
+	groff -mandoc -Thtml cpg_dispatch.3 > html/cpg_dispatch.html
+	groff -mandoc -Thtml cpg_join.3 > html/cpg_join.html
+	groff -mandoc -Thtml cpg_leave.3 > html/cpg_leave.html
+	groff -mandoc -Thtml cpg_mcast_joined.3 > html/cpg_mcast_joined.html
+	groff -mandoc -Thtml cpg_membership_get.3 > html/cpg_membership_get.html
+
 	cp index.html html
 
 clean:

man/cpg_dispatch.3

@@ -0,0 +1,100 @@
+.\"/*
+.\" * Copyright (c) 2006 Red Hat, Inc.
+.\" *
+.\" * All rights reserved.
+.\" *
+.\" * Author: Patrick Caulfield <pcaulfie@redhat.com>
+.\" *
+.\" * This software licensed under BSD license, the text of which follows:
+.\" * 
+.\" * Redistribution and use in source and binary forms, with or without
+.\" * modification, are permitted provided that the following conditions are met:
+.\" *
+.\" * - Redistributions of source code must retain the above copyright notice,
+.\" *   this list of conditions and the following disclaimer.
+.\" * - Redistributions in binary form must reproduce the above copyright notice,
+.\" *   this list of conditions and the following disclaimer in the documentation
+.\" *   and/or other materials provided with the distribution.
+.\" * - Neither the name of the MontaVista Software, Inc. nor the names of its
+.\" *   contributors may be used to endorse or promote products derived from this
+.\" *   software without specific prior written permission.
+.\" *
+.\" * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+.\" * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+.\" * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+.\" * THE POSSIBILITY OF SUCH DAMAGE.
+.\" */
+.TH CPG_DISPATCH 3 2004-08-31 "openais Man Page" "Openais Programmer's Manual"
+.SH NAME
+cpg_dispatch \- Dispatches callbacks from the CPG service
+.SH SYNOPSIS
+.B #include <openais/cpg.h>
+.sp
+.BI "int cpg_dispatch(cpg_handle_t " handle ", cpg_dispatch_t *" dispatch_types ");
+.SH DESCRIPTION
+The
+.B cpg_dispatch
+function is used to dispatch configuration changes or messages from the
+closed process groups API.
+.PP
+Each application may have several connections to the CPG API.  Each  application
+uses the 
+.I handle
+argument to uniquely identify the connection.
+.PP
+The
+.I dispatch_types
+argument is used to identify the type of dispatch to execute.  The possible types are
+defined by the structure:
+
+.IP
+.RS
+.ne 18
+.nf
+.ta 4n 30n 33n
+typedef enum {
+        CPG_DISPATCH_ONE,
+        CPG_DISPATCH_ALL,
+        CPG_DISPATCH_BLOCKING
+} cpg_dispatch_t;
+.ta
+.fi
+.RE
+.IP
+.PP
+.PP
+The dispatch values have the following meanings:
+.TP
+.B CPG_DISPATCH_ONE
+Dispatch atleast one callback, blocking until the callback is dispatched.
+.TP
+.B CPG_DISPATCH_ALL
+Dispatch all waiting callbacks without blocking to wait for any callbacks.
+.TP
+.B CPG_DISPATCH_BLOCKING
+Dispatch all callbacks blocking indefinately.  This is used in a threaded
+program where a thread is created, and then cpg_dispatch() is called immediately
+from the created thread to execute callbacks.
+
+.SH RETURN VALUE
+This call returns the CPG_OK value if successful, otherwise an error is returned.
+.PP
+.SH ERRORS
+The errors are undocumented.
+.SH "SEE ALSO"
+.BR cpg_overview (8),
+.BR cpg_initialize (3),
+.BR cpg_finalize (3),
+.BR cpg_fd_get (3),
+.BR cpg_join (3),
+.BR cpg_leave (3),
+.BR cpg_mcast_joined (3),
+.BR cpg_membership_get (3)
+.PP

man/cpg_fd_get.3

@@ -0,0 +1,67 @@
+.\"/*
+.\" * Copyright (c) 2006 Red Hat, Inc.
+.\" *
+.\" * All rights reserved.
+.\" *
+.\" * Author: Patrick Caulfield <pcaulfie@redhat.com>
+.\" *
+.\" * This software licensed under BSD license, the text of which follows:
+.\" * 
+.\" * Redistribution and use in source and binary forms, with or without
+.\" * modification, are permitted provided that the following conditions are met:
+.\" *
+.\" * - Redistributions of source code must retain the above copyright notice,
+.\" *   this list of conditions and the following disclaimer.
+.\" * - Redistributions in binary form must reproduce the above copyright notice,
+.\" *   this list of conditions and the following disclaimer in the documentation
+.\" *   and/or other materials provided with the distribution.
+.\" * - Neither the name of the MontaVista Software, Inc. nor the names of its
+.\" *   contributors may be used to endorse or promote products derived from this
+.\" *   software without specific prior written permission.
+.\" *
+.\" * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+.\" * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+.\" * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+.\" * THE POSSIBILITY OF SUCH DAMAGE.
+.\" */
+.TH CPG_FD_GET 3 2004-08-31 "openais Man Page" "Openais Programmer's Manual"
+.SH NAME
+cpg_fd_get \- Dispatches callbacks from the CPG service
+.SH SYNOPSIS
+.B #include <openais/cpg.h>
+.sp
+.BI "int cpg_fd_get(cpg_handle_t " handle ", int *" fd ");
+.SH DESCRIPTION
+The
+.B cpg_fd_get
+function is used to retrieve the file descriptor that may be used with the poll
+system call to determine when
+.B cpg_dispatch(3)
+won't block.  The
+.I handle
+argument may not be used directly with
+.B poll
+because it is not the file descriptor, but instead an internal identifier used
+by the CPG library.
+.SH RETURN VALUE
+This call returns the CPG_OK value if successful, otherwise an error is returned.
+.PP
+.SH ERRORS
+The errors are undocumented.
+.SH "SEE ALSO"
+.BR cpg_overview (8),
+.BR cpg_initialize (3),
+.BR cpg_finalize (3),
+.BR cpg_dispatch (3),
+.BR cpg_join (3),
+.BR cpg_leave (3),
+.BR cpg_mcast_joined (3),
+.BR cpg_membership_get (3)
+.PP

man/cpg_finalize.3

@@ -0,0 +1,63 @@
+.\"/*
+.\" * Copyright (c) 2006 Red Hat, Inc.
+.\" *
+.\" * All rights reserved.
+.\" *
+.\" * Author: Patrick Caulfield <pcaulfie@redhat.com>
+.\" *
+.\" * This software licensed under BSD license, the text of which follows:
+.\" * 
+.\" * Redistribution and use in source and binary forms, with or without
+.\" * modification, are permitted provided that the following conditions are met:
+.\" *
+.\" * - Redistributions of source code must retain the above copyright notice,
+.\" *   this list of conditions and the following disclaimer.
+.\" * - Redistributions in binary form must reproduce the above copyright notice,
+.\" *   this list of conditions and the following disclaimer in the documentation
+.\" *   and/or other materials provided with the distribution.
+.\" * - Neither the name of the MontaVista Software, Inc. nor the names of its
+.\" *   contributors may be used to endorse or promote products derived from this
+.\" *   software without specific prior written permission.
+.\" *
+.\" * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+.\" * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+.\" * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+.\" * THE POSSIBILITY OF SUCH DAMAGE.
+.\" */
+.TH EVS_FINALIZE 3 2004-08-31 "openais Man Page" "Openais Programmer's Manual"
+.SH NAME
+cpg_finalize \- Terminate a connection to the CPG service
+.SH SYNOPSIS
+.B #include <openais/cpg.h>
+.sp
+.BI "int cpg_finalize(cpg_handle_t " handle ");
+.SH DESCRIPTION
+The
+.B cpg_finalize
+function is used to close a connection to the closed process group API.
+Once the connection is finalized, the handle may not be used again by applications.
+No more callbacks will be dispatched from the
+.B cpg_dispatch function.
+.PP
+.SH RETURN VALUE
+This call returns the CPG_OK value if successful, otherwise an error is returned.
+.PP
+.SH ERRORS
+The errors are undocumented.
+.SH "SEE ALSO"
+.BR cpg_overview (8),
+.BR cpg_initialize (3),
+.BR cpg_fd_get (3),
+.BR cpg_dispatch (3),
+.BR cpg_join (3),
+.BR cpg_leave (3),
+.BR cpg_mcast_joined (3),
+.BR cpg_membership_get (3)
+.PP

man/cpg_initialise.3

@@ -0,0 +1,160 @@
+.\"/*
+.\" * Copyright (c) 2006 Red Hat, Inc.
+.\" *
+.\" * All rights reserved.
+.\" *
+.\" * Author: Patrick Caulfield <pcaulfie@redhat.com>
+.\" *
+.\" * This software licensed under BSD license, the text of which follows:
+.\" * 
+.\" * Redistribution and use in source and binary forms, with or without
+.\" * modification, are permitted provided that the following conditions are met:
+.\" *
+.\" * - Redistributions of source code must retain the above copyright notice,
+.\" *   this list of conditions and the following disclaimer.
+.\" * - Redistributions in binary form must reproduce the above copyright notice,
+.\" *   this list of conditions and the following disclaimer in the documentation
+.\" *   and/or other materials provided with the distribution.
+.\" * - Neither the name of the MontaVista Software, Inc. nor the names of its
+.\" *   contributors may be used to endorse or promote products derived from this
+.\" *   software without specific prior written permission.
+.\" *
+.\" * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+.\" * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+.\" * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+.\" * THE POSSIBILITY OF SUCH DAMAGE.
+.\" */
+.TH CPG_INITIALIZE 3 2004-08-31 "openais Man Page" "Openais Programmer's Manual"
+.SH NAME
+evs_initialize \- Create a new connection to the CPG service
+.SH SYNOPSIS
+.B #include <openais/cpg.h>
+.sp
+.BI "int cpg_initialize(evs_handle_t *" handle ", cpg_callbacks_t *" callbacks ");
+.SH DESCRIPTION
+The
+.B cpg_initialize
+function is used to initialize a connection to the closed process groups API.
+.PP
+Each application may have several connections to the CPG API.  Each  application
+uses the 
+.I handle
+argument to uniquely identify the connection.  The
+.I handle
+argument is then used in other function calls to identify the connection to be used
+for communication with the CPG service.
+.PP
+Every time an CPG event occurs within the joined group, one of the callbacks specified by the argument
+.I callbacks
+is called.  The callback functions are described by the following type definitions:
+.PP
+.IP
+.RS
+.ne 18
+.nf
+.ta 4n 20n 32n
+typedef void (*cpg_deliver_fn_t) (
+        cpg_handle_t handle,
+        struct cpg_name *group_name,
+	uint32_t nodeid,
+	uint32_t pid,
+	void *msg,
+	int msg_len);
+
+
+typedef void (*cpg_confchg_fn_t) (
+	cpg_handle_t handle,
+	struct cpg_name *group_name,
+	struct cpg_address *member_list, int member_list_entries,
+	struct cpg_address *left_list, int left_list_entries,
+	struct cpg_address *joined_list, int joined_list_entries);
+.ta
+.fi
+.RE
+.IP
+.PP
+.PP
+The
+.I callbacks
+argument is of the type:
+.IP
+.RS
+.ne 18
+.nf
+.PP
+typedef struct {
+        cpg_deliver_fn_t cpg_deliver_fn;
+        cpg_confchg_fn_t cpg_confchg_fn;
+} cpg_callbacks_t;
+.ta
+.fi
+.RE
+.IP
+.PP
+When a configuration change occurs or a message is to be delivered one of the callbacks
+is called from the
+.B cpg_dispatch()
+function.  If a configuration change occurs,
+.I cpg_confchg_fn
+is called.  If a delivery of a message occurs,
+.I cpg_deliver_fn
+is called.
+
+The
+.I cpg_address
+structure is defined 
+.IP
+.RS
+.ne 18
+.nf
+.PP
+struct cpg_address {
+        unsigned int nodeid;
+        unsigned int pid;
+        unsigned int reason;
+};
+.ta
+.fi
+.RE
+.IP
+.PP
+where nodeid is a 32 bit unique node identifier, pid is the process ID of the process that has joined/left the group
+or sent the message, and reason is an integer code indicating why the node join/left the group.
+.BR
+.IP
+.RS
+.ne 18
+.nf
+.PP
+CPG_REASON_JOIN     - the process joined a group using cpg_join().
+CPG_REASON_LEAVE    - the process left a group using cpg_leave()
+CPG_REASON_NODEDOWN - the process left a group because the node left the cluster.
+CPG_REASON_NODEUP   - the process joined a group because it was already a member of a group on a node that has just joined the cluster
+CPG_REASON_PROCDOWN - the process left a group without calling cpg_leave()
+.ta
+.fi
+.RE
+.IP
+.PP
+.SH RETURN VALUE
+This call returns the CPG_OK value if successful, otherwise an error is returned.
+.PP
+.SH ERRORS
+The errors are undocumented.
+.SH "SEE ALSO"
+.BR cpg_overview (8),
+.BR cpg_finalize (3),
+.BR cpg_fd_get (3),
+.BR cpg_dispatch (3),
+.BR cpg_join (3),
+.BR cpg_leave (3),
+.BR cpg_mcast_joined (3),
+.BR cpg_mmembership_get (3)
+.PP

man/cpg_initialize.3

@@ -0,0 +1,162 @@
+.\"/*
+.\" * Copyright (c) 2006 Red Hat, Inc.
+.\" *
+.\" * All rights reserved.
+.\" *
+.\" * Author: Patrick Caulfield <pcaulfie@redhat.com>
+.\" *
+.\" * This software licensed under BSD license, the text of which follows:
+.\" * 
+.\" * Redistribution and use in source and binary forms, with or without
+.\" * modification, are permitted provided that the following conditions are met:
+.\" *
+.\" * - Redistributions of source code must retain the above copyright notice,
+.\" *   this list of conditions and the following disclaimer.
+.\" * - Redistributions in binary form must reproduce the above copyright notice,
+.\" *   this list of conditions and the following disclaimer in the documentation
+.\" *   and/or other materials provided with the distribution.
+.\" * - Neither the name of the MontaVista Software, Inc. nor the names of its
+.\" *   contributors may be used to endorse or promote products derived from this
+.\" *   software without specific prior written permission.
+.\" *
+.\" * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+.\" * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+.\" * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+.\" * THE POSSIBILITY OF SUCH DAMAGE.
+.\" */
+.TH CPG_INITIALIZE 3 2004-08-31 "openais Man Page" "Openais Programmer's Manual"
+.SH NAME
+evs_initialize \- Create a new connection to the CPG service
+.SH SYNOPSIS
+.B #include <openais/cpg.h>
+.sp
+.BI "int cpg_initialize(evs_handle_t *" handle ", cpg_callbacks_t *" callbacks ");
+.SH DESCRIPTION
+The
+.B cpg_initialize
+function is used to initialize a connection to the closed process groups API.
+.PP
+Each application may have several connections to the CPG API.  Each  application
+uses the 
+.I handle
+argument to uniquely identify the connection.  The
+.I handle
+argument is then used in other function calls to identify the connection to be used
+for communication with the CPG service.
+.PP
+Every time an CPG event occurs within the joined group, one of the callbacks specified by the argument
+.I callbacks
+is called.  The callback functions are described by the following type definitions:
+.PP
+.PP
+.IP
+.RS
+.ne 18
+.nf
+.ta 4n 20n 32n
+
+typedef void (*cpg_deliver_fn_t) (
+        cpg_handle_t handle,
+        struct cpg_name *group_name,
+        uint32_t nodeid,
+        uint32_t pid,
+        void *msg,
+        int msg_len);
+
+
+typedef void (*cpg_confchg_fn_t) (
+        cpg_handle_t handle,
+        struct cpg_name *group_name,
+        struct cpg_address *member_list, int member_list_entries,
+        struct cpg_address *left_list, int left_list_entries,
+        struct cpg_address *joined_list, int joined_list_entries);
+.ta
+.fi
+.RE
+.IP
+.PP
+.PP
+The
+.I callbacks
+argument is of the type:
+.IP
+.RS
+.ne 18
+.nf
+.PP
+typedef struct {
+        cpg_deliver_fn_t cpg_deliver_fn;
+        cpg_confchg_fn_t cpg_confchg_fn;
+} cpg_callbacks_t;
+.ta
+.fi
+.RE
+.IP
+.PP
+When a configuration change occurs or a message is to be delivered one of the callbacks
+is called from the
+.B cpg_dispatch()
+function.  If a configuration change occurs,
+.I cpg_confchg_fn
+is called.  If a delivery of a message occurs,
+.I cpg_deliver_fn
+is called.
+
+The
+.I cpg_address
+structure is defined 
+.IP
+.RS
+.ne 18
+.nf
+.PP
+struct cpg_address {
+        unsigned int nodeid;
+        unsigned int pid;
+        unsigned int reason;
+};
+.ta
+.fi
+.RE
+.IP
+.PP
+where nodeid is a 32 bit unique node identifier, pid is the process ID of the process that has joined/left the group
+or sent the message, and reason is an integer code indicating why the node join/left the group.
+.PP
+.IP
+.RS
+.ne 18
+.nf
+.PP
+CPG_REASON_JOIN     - the process joined a group using cpg_join().
+CPG_REASON_LEAVE    - the process left a group using cpg_leave()
+CPG_REASON_NODEDOWN - the process left a group because the node left the cluster.
+CPG_REASON_NODEUP   - the process joined a group because it was already a member of a group on a node that has just joined the cluster
+CPG_REASON_PROCDOWN - the process left a group without calling cpg_leave()
+.ta
+.fi
+.RE
+.IP
+.PP
+.SH RETURN VALUE
+This call returns the CPG_OK value if successful, otherwise an error is returned.
+.PP
+.SH ERRORS
+The errors are undocumented.
+.SH "SEE ALSO"
+.BR cpg_overview (8),
+.BR cpg_finalize (3),
+.BR cpg_fd_get (3),
+.BR cpg_dispatch (3),
+.BR cpg_join (3),
+.BR cpg_leave (3),
+.BR cpg_mcast_joined (3),
+.BR cpg_mmembership_get (3)
+.PP

man/cpg_join.3

@@ -0,0 +1,104 @@
+.\"/*
+.\" * Copyright (c) 2006 Red Hat, Inc.
+.\" *
+.\" * All rights reserved.
+.\" *
+.\" * Author: Patrick Caulfield <pcaulfie@redhat.com>
+.\" *
+.\" * This software licensed under BSD license, the text of which follows:
+.\" * 
+.\" * Redistribution and use in source and binary forms, with or without
+.\" * modification, are permitted provided that the following conditions are met:
+.\" *
+.\" * - Redistributions of source code must retain the above copyright notice,
+.\" *   this list of conditions and the following disclaimer.
+.\" * - Redistributions in binary form must reproduce the above copyright notice,
+.\" *   this list of conditions and the following disclaimer in the documentation
+.\" *   and/or other materials provided with the distribution.
+.\" * - Neither the name of the MontaVista Software, Inc. nor the names of its
+.\" *   contributors may be used to endorse or promote products derived from this
+.\" *   software without specific prior written permission.
+.\" *
+.\" * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+.\" * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+.\" * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+.\" * THE POSSIBILITY OF SUCH DAMAGE.
+.\" */
+.TH CPG_JOIN 3 2004-08-31 "openais Man Page" "Openais Programmer's Manual"
+.SH NAME
+cpg_join \- Joins one or more groups in the CPG library
+.SH SYNOPSIS
+.B #include <openais/cpg.h>
+.sp
+.BI "int cpg_join(cpg_handle_t " handle ", struct cpg_name *" group ");
+.SH DESCRIPTION
+The
+.B cpg_join
+function is used to join one group.  When a group is joined, using the
+.B cpg_mcast_joined(3)
+function will multicast to the groups joined in the argument
+.I handle. 
+The process will also get notifications of other processes joining
+and leaving the group.
+Messages that are sent to any of the groups joined to the parameter
+.I handle
+will be delivered by
+.B cpg_dispatch(3).
+.PP
+This function may be only be called once for each handle. When a group has been joined
+the process will start to receive callbacks relating to messages send from members
+of the group or notifications of process joining/leaving the group.
+.PP
+Note that more than one process can join a CPG group and each will receive its
+own copy of any messages sent using 
+.I cpg_mcast_joined()
+and its own confchg callback.
+.PP
+
+The argument
+.I group
+is used to specify the group to join.  
+
+
+The
+.I groups
+argument is of the type struct cpg_name which is defined by the structure:
+
+.IP
+.RS
+.ne 18
+.nf
+.ta 4n 30n 33n
+struct cpg_name {
+        int length;
+        char value[128];
+};
+.ta
+.fi
+.RE
+.IP
+.PP
+.PP
+.SH RETURN VALUE
+This call returns the CPG_OK value if successful, CPG_ERR_INVALID_PARAM if the
+handle is already joined to a group.
+.PP
+.SH ERRORS
+Not all errors are documented.
+.SH "SEE ALSO"
+.BR cpg_overview (8),
+.BR cpg_initialize (3),
+.BR cpg_finalize (3),
+.BR cpg_fd_get (3),
+.BR cpg_dispatch (3),
+.BR cpg_leave (3),
+.BR cpg_mcast_joined (3),
+.BR cpg_membership_get (3)
+.PP

man/cpg_leave.3

@@ -0,0 +1,69 @@
+.\"/*
+.\" * Copyright (c) 2006 Red Hat, Inc.
+.\" *
+.\" * All rights reserved.
+.\" *
+.\" * Author: Patrick Caulfield <pcaulfie@redhat.com>
+.\" *
+.\" * This software licensed under BSD license, the text of which follows:
+.\" * 
+.\" * Redistribution and use in source and binary forms, with or without
+.\" * modification, are permitted provided that the following conditions are met:
+.\" *
+.\" * - Redistributions of source code must retain the above copyright notice,
+.\" *   this list of conditions and the following disclaimer.
+.\" * - Redistributions in binary form must reproduce the above copyright notice,
+.\" *   this list of conditions and the following disclaimer in the documentation
+.\" *   and/or other materials provided with the distribution.
+.\" * - Neither the name of the MontaVista Software, Inc. nor the names of its
+.\" *   contributors may be used to endorse or promote products derived from this
+.\" *   software without specific prior written permission.
+.\" *
+.\" * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+.\" * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+.\" * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+.\" * THE POSSIBILITY OF SUCH DAMAGE.
+.\" */
+.TH CPG_LEAVE 3 2004-08-31 "openais Man Page" "Openais Programmer's Manual"
+.SH NAME
+cpg_leave \- Leave a group in the CPG library
+.SH SYNOPSIS
+.B #include <openais/cpg.h>
+.sp
+.BI "int cpg_leave(cpg_handle_t " handle ", struct cpg_name *" group ");
+.SH DESCRIPTION
+The
+.B cpg_leave
+function is used to leave a group.  Once a group has been left the process will
+no longer receive messages or notifications about events in that group. NOTE: that a group is 
+only deemed to have left the group once it has been notified (by its confchg callback)
+that is has left. So expect to receive at least one confchg callback after calling
+this function.
+
+The argument
+.I group
+is used to specify the group to leave. It is currently ignored as only one group
+can be joined per handle. It is included here for to allow for future development.
+
+.SH RETURN VALUE
+This call returns the CPG_OK value if successful, otherwise an error is returned.
+.PP
+.SH ERRORS
+The errors are undocumented.
+.SH "SEE ALSO"
+.BR cpg_overview (8),
+.BR cpg_initialize (3),
+.BR cpg_finalize (3),
+.BR cpg_fd_get (3),
+.BR cpg_dispatch (3),
+.BR cpg_join (3),
+.BR cpg_mcast_joined (3),
+.BR cpg_membership_get (3)
+.PP

man/cpg_mcast_joined.3

@@ -0,0 +1,134 @@
+.\"/*
+.\" * Copyright (c) 2006 Red Hat, Inc.
+.\" *
+.\" * All rights reserved.
+.\" *
+.\" * Author: Patrick Caulfield <pcaulfie@redhat.com>
+.\" *
+.\" * This software licensed under BSD license, the text of which follows:
+.\" * 
+.\" * Redistribution and use in source and binary forms, with or without
+.\" * modification, are permitted provided that the following conditions are met:
+.\" *
+.\" * - Redistributions of source code must retain the above copyright notice,
+.\" *   this list of conditions and the following disclaimer.
+.\" * - Redistributions in binary form must reproduce the above copyright notice,
+.\" *   this list of conditions and the following disclaimer in the documentation
+.\" *   and/or other materials provided with the distribution.
+.\" * - Neither the name of the MontaVista Software, Inc. nor the names of its
+.\" *   contributors may be used to endorse or promote products derived from this
+.\" *   software without specific prior written permission.
+.\" *
+.\" * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+.\" * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+.\" * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+.\" * THE POSSIBILITY OF SUCH DAMAGE.
+.\" */
+.TH CPG_MCAST_JOINED 3 3004-08-31 "openais Man Page" "Openais Programmer's Manual"
+.SH NAME
+cpg_join \- Multicasts to all groups joined to a handle
+.SH SYNOPSIS
+.B #include <sys/uio.h>
+.B #include <openais/cpg.h>
+.sp
+.BI "int cpg_mcast_joined(cpg_handle_t " handle ", cpg_gurantee_t " guarantee ", struct iovec *" iovec ", int " iov_len ");
+.SH DESCRIPTION
+The
+.B cpg_mcast_joined
+function is multicast a message to all the processes that have been joined with the
+.B cpg_join(3)
+funtion for the same group name.
+.I handle.
+Messages that are sent to any of the groups joined to the parameter
+.I handle
+will be delivered to all subscribed processes in the system.
+.PP
+The argument
+.I guarantee
+requests a delivery guarantee for the message to be sent.  The cpg_guarantee_t type is
+defined by:
+.IP
+.RS
+.ne 18
+.nf
+.ta 4n 30n 33n
+typedef enum {
+        CPG_TYPE_UNORDERED,     /* not implemented */
+        CPG_TYPE_FIFO,          /* same as agreed */
+        CPG_TYPE_AGREED,        /* implemented */
+        CPG_TYPE_SAFE           /* not implemented */
+} cpg_guarantee_t;
+.ta
+.fi
+.RE
+.IP
+.PP
+.PP
+The meanings of the cpg_gaurantee_t typedef are:
+.TP
+.B CPG_GUARANTEE_UNORDERED
+Messages are guaranteed to be delivered, but with no particular order.  This 
+mode is unimplemented in the CPG library.
+.TP
+.B CPG_GUARANTEE_FIFO
+Messages are guaranteed to be delivered in first sent first delivery order
+from one one.  In fact, this guarantee is actually the AGREED guarantee.
+.TP
+.B CPG_GUARANTEE_AGREED
+All processors must agree on the order of delivery.  If a message is sent
+from two or more processors at about the same time, the delivery will occur
+in the same order to all processors.
+.TP
+.B CPG_GUARANTEE_SAFE
+All processors must agree on the order of delivery.  Further all processors
+must have a copy of the message before any delivery takes place.  This mode is
+unimplemented in the CPG library.
+.PP
+The
+.I iovec
+argument describes the scatter/gather list which is used to transmit a message.  This
+is a standard socket structure described by:
+.IP
+.RS
+.ne 18
+.nf
+.ta 4n 30n 33n
+struct iovec
+{
+        void *iov_base;     /* Pointer to data.  */
+        size_t iov_len;     /* Length of data.  */
+};
+.ta
+.fi
+.RE
+.IP
+.PP
+.PP
+The
+.I iovlen
+argument describes the number of entires in the
+.I iovec
+argument.  
+
+.SH RETURN VALUE
+This call returns the CPG_OK value if successful, otherwise an error is returned.
+.PP
+.SH ERRORS
+The errors are undocumented.
+.SH "SEE ALSO"
+.BR cpg_overview (8),
+.BR cpg_initialize (3),
+.BR cpg_finalize (3),
+.BR cpg_fd_get (3),
+.BR cpg_dispatch (3),
+.BR cpg_leave (3),
+.BR cpg_join (3),
+.BR cpg_membership_get (3)
+.PP

man/cpg_membership_get.3

@@ -0,0 +1,73 @@
+.\"/*
+.\" * Copyright (c) 2006 Red Hat, Inc.
+.\" *
+.\" * All rights reserved.
+.\" *
+.\" * Author: Patrick Caulfield <pcaulfie@redhat.com>
+.\" *
+.\" * This software licensed under BSD license, the text of which follows:
+.\" * 
+.\" * Redistribution and use in source and binary forms, with or without
+.\" * modification, are permitted provided that the following conditions are met:
+.\" *
+.\" * - Redistributions of source code must retain the above copyright notice,
+.\" *   this list of conditions and the following disclaimer.
+.\" * - Redistributions in binary form must reproduce the above copyright notice,
+.\" *   this list of conditions and the following disclaimer in the documentation
+.\" *   and/or other materials provided with the distribution.
+.\" * - Neither the name of the MontaVista Software, Inc. nor the names of its
+.\" *   contributors may be used to endorse or promote products derived from this
+.\" *   software without specific prior written permission.
+.\" *
+.\" * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+.\" * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+.\" * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+.\" * THE POSSIBILITY OF SUCH DAMAGE.
+.\" */
+.TH CPG_MEMBERSHIP_GET 3 2006-02-06 "openais Man Page" "Openais Programmer's Manual"
+.SH NAME
+cpg_membership_get \- Returns a list of members of a CPG library group
+.SH SYNOPSIS
+.B #include <openais/cpg.h>
+.sp
+.BI "int cpg_membership_get(cpg_handle_t " handle ", struct cpg_name *" groupName ", struct cpg_address *" member_list ", int *" member_list_entries ");
+.SH DESCRIPTION
+The
+.B cpg_membership_get
+function is used to determine the current processes in the configuration. You probably will not
+need to call this function much as one of the first confchg callbacks you will get will be from
+the cpg_join() function containing your process.
+.BR
+The argument
+.I handle
+is used to reference the cpg instantiation.
+The argument 
+.I groupName
+will return the name of the group
+The argument
+.I member_list
+will return the list of processors in the current membership.
+The argument
+.I member_list_entries
+should be set with the size of member_list and will return the size of the
+member_list after return from the function.
+.PP
+.SH ERRORS
+The errors are undocumented.
+.SH "SEE ALSO"
+.BR cpg_overview (8),
+.BR cpg_initialize (3),
+.BR cpg_finalize (3),
+.BR cpg_fd_get (3),
+.BR cpg_dispatch (3),
+.BR cpg_leave (3),
+.BR cpg_mcast_joined (3),
+.BR cpg_membership_get (3)
+.PP

man/cpg_overview.8

@@ -0,0 +1,64 @@
+.\"/*
+.\" * Copyright (c) 2006 Red Hat, Inc.
+.\" *
+.\" * All rights reserved.
+.\" *
+.\" * Author: Patrick Caulfield <pcaulfie@redhat.com>
+.\" *
+.\" * This software licensed under BSD license, the text of which follows:
+.\" * 
+.\" * Redistribution and use in source and binary forms, with or without
+.\" * modification, are permitted provided that the following conditions are met:
+.\" *
+.\" * - Redistributions of source code must retain the above copyright notice,
+.\" *   this list of conditions and the following disclaimer.
+.\" * - Redistributions in binary form must reproduce the above copyright notice,
+.\" *   this list of conditions and the following disclaimer in the documentation
+.\" *   and/or other materials provided with the distribution.
+.\" * - Neither the name of the MontaVista Software, Inc. nor the names of its
+.\" *   contributors may be used to endorse or promote products derived from this
+.\" *   software without specific prior written permission.
+.\" *
+.\" * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+.\" * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+.\" * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+.\" * THE POSSIBILITY OF SUCH DAMAGE.
+.\" */
+.TH CPG_OVERVIEW 8 2006-03-06 "openais Man Page" "Openais Programmer's Manual"
+.SH OVERVIEW
+The CPG library is delivered with the openais project.  This library is used
+to create distributed applications that operate properly during partitions, merges,
+and faults.
+.PP
+The library provides a mechanism to:
+* handle abstraction for multiple instances of an CPG library in one application
+* join one or more groups
+* leave one or more groups
+* Deliver messages to members of that group
+* Deliver configuration changes
+.PP
+.SH SECURITY
+The CPG library encrypts all messages sent over the network using the SOBER-128
+stream cipher.  The EVS library uses HMAC and SHA1 to authenticate all messages.
+The CPG library uses SOBER-128 as a pseudo random number generator.  TheCPG
+library feeds the PRNG using the /dev/random Linux device.
+.SH BUGS
+This software is not yet production, so there may still be some bugs.
+.SH "SEE ALSO"
+.BR cpg_initialize (3),
+.BR cpg_finalize (3),
+.BR cpg_fd_get (3),
+.BR cpg_dispatch (3),
+.BR cpg_join (3),
+.BR cpg_leave (3),
+.BR cpg_mcast_joined (3),
+.BR cpg_mmembership_get (3)
+
+.PP

man/index.html

@@ -1,6 +1,6 @@
 <html>
 <head>
-<title>EVS Documentation</title>
+<title>EVS & CPG Documentation</title>
 </head>
 <body>
 
@@ -33,4 +33,23 @@ Welcome to the openais project's manual pages.
 <BR>
 <A HREF="evs_membership_get.html">evs_membership_get(3)</A>: Description of the evs_membership_get interface.
 <BR>
+
+<A HREF="cpg_overview.html">cpg_overview(8)</A>: Overview of the cpg extended virtual synchrony group communication toolkit.
+<BR>
+<A HREF="cpg_initialize.html">cpg_initialize(3)</A>: Description of the cpg_initialize interface.
+<BR>
+<A HREF="cpg_finalize.html">cpg_finalize(3)</A>: Description of the cpg_finalize interface.
+<BR>
+<A HREF="cpg_dispatch.html">cpg_dispatch(3)</A>: Description of the cpg_dispatch interface.
+<BR>
+<A HREF="cpg_fd_get.html">cpg_fd_get(3)</A>: Description of the cpg_fd_get interface.
+<BR>
+<A HREF="cpg_join.html">cpg_join(3)</A>: Description of the cpg_join interface.
+<BR>
+<A HREF="cpg_leave.html">cpg_leave(3)</A>: Description of the cpg_leave interface.
+<BR>
+<A HREF="cpg_mcast_joined.html">cpg_mcast_joined(3)</A>: Description of the cpg_mcast_joined interface.
+<BR>
+<A HREF="cpg_membership_get.html">cpg_membership_get(3)</A>: Description of the cpg_membership_get interface.
+
 </body>