diff --git a/man/Makefile b/man/Makefile index b05f8e36..e6cc827c 100644 --- a/man/Makefile +++ b/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: diff --git a/man/cpg_dispatch.3 b/man/cpg_dispatch.3 new file mode 100644 index 00000000..1d225838 --- /dev/null +++ b/man/cpg_dispatch.3 @@ -0,0 +1,100 @@ +.\"/* +.\" * Copyright (c) 2006 Red Hat, Inc. +.\" * +.\" * All rights reserved. +.\" * +.\" * Author: Patrick Caulfield +.\" * +.\" * 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 +.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 diff --git a/man/cpg_fd_get.3 b/man/cpg_fd_get.3 new file mode 100644 index 00000000..87b43987 --- /dev/null +++ b/man/cpg_fd_get.3 @@ -0,0 +1,67 @@ +.\"/* +.\" * Copyright (c) 2006 Red Hat, Inc. +.\" * +.\" * All rights reserved. +.\" * +.\" * Author: Patrick Caulfield +.\" * +.\" * 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 +.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 diff --git a/man/cpg_finalize.3 b/man/cpg_finalize.3 new file mode 100644 index 00000000..9b5bb1ad --- /dev/null +++ b/man/cpg_finalize.3 @@ -0,0 +1,63 @@ +.\"/* +.\" * Copyright (c) 2006 Red Hat, Inc. +.\" * +.\" * All rights reserved. +.\" * +.\" * Author: Patrick Caulfield +.\" * +.\" * 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 +.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 diff --git a/man/cpg_initialise.3 b/man/cpg_initialise.3 new file mode 100644 index 00000000..2a0c299a --- /dev/null +++ b/man/cpg_initialise.3 @@ -0,0 +1,160 @@ +.\"/* +.\" * Copyright (c) 2006 Red Hat, Inc. +.\" * +.\" * All rights reserved. +.\" * +.\" * Author: Patrick Caulfield +.\" * +.\" * 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 +.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 diff --git a/man/cpg_initialize.3 b/man/cpg_initialize.3 new file mode 100644 index 00000000..1cd89591 --- /dev/null +++ b/man/cpg_initialize.3 @@ -0,0 +1,162 @@ +.\"/* +.\" * Copyright (c) 2006 Red Hat, Inc. +.\" * +.\" * All rights reserved. +.\" * +.\" * Author: Patrick Caulfield +.\" * +.\" * 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 +.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 diff --git a/man/cpg_join.3 b/man/cpg_join.3 new file mode 100644 index 00000000..b1459178 --- /dev/null +++ b/man/cpg_join.3 @@ -0,0 +1,104 @@ +.\"/* +.\" * Copyright (c) 2006 Red Hat, Inc. +.\" * +.\" * All rights reserved. +.\" * +.\" * Author: Patrick Caulfield +.\" * +.\" * 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 +.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 diff --git a/man/cpg_leave.3 b/man/cpg_leave.3 new file mode 100644 index 00000000..cdcf8cbb --- /dev/null +++ b/man/cpg_leave.3 @@ -0,0 +1,69 @@ +.\"/* +.\" * Copyright (c) 2006 Red Hat, Inc. +.\" * +.\" * All rights reserved. +.\" * +.\" * Author: Patrick Caulfield +.\" * +.\" * 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 +.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 diff --git a/man/cpg_mcast_joined.3 b/man/cpg_mcast_joined.3 new file mode 100644 index 00000000..1013b2c8 --- /dev/null +++ b/man/cpg_mcast_joined.3 @@ -0,0 +1,134 @@ +.\"/* +.\" * Copyright (c) 2006 Red Hat, Inc. +.\" * +.\" * All rights reserved. +.\" * +.\" * Author: Patrick Caulfield +.\" * +.\" * 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 +.B #include +.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 diff --git a/man/cpg_membership_get.3 b/man/cpg_membership_get.3 new file mode 100644 index 00000000..2555d0bb --- /dev/null +++ b/man/cpg_membership_get.3 @@ -0,0 +1,73 @@ +.\"/* +.\" * Copyright (c) 2006 Red Hat, Inc. +.\" * +.\" * All rights reserved. +.\" * +.\" * Author: Patrick Caulfield +.\" * +.\" * 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 +.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 diff --git a/man/cpg_overview.8 b/man/cpg_overview.8 new file mode 100644 index 00000000..74e4617f --- /dev/null +++ b/man/cpg_overview.8 @@ -0,0 +1,64 @@ +.\"/* +.\" * Copyright (c) 2006 Red Hat, Inc. +.\" * +.\" * All rights reserved. +.\" * +.\" * Author: Patrick Caulfield +.\" * +.\" * 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 diff --git a/man/index.html b/man/index.html index fd87f788..8f8b9158 100644 --- a/man/index.html +++ b/man/index.html @@ -1,6 +1,6 @@ -EVS Documentation +EVS & CPG Documentation @@ -33,4 +33,23 @@ Welcome to the openais project's manual pages.
evs_membership_get(3): Description of the evs_membership_get interface.
+ +cpg_overview(8): Overview of the cpg extended virtual synchrony group communication toolkit. +
+cpg_initialize(3): Description of the cpg_initialize interface. +
+cpg_finalize(3): Description of the cpg_finalize interface. +
+cpg_dispatch(3): Description of the cpg_dispatch interface. +
+cpg_fd_get(3): Description of the cpg_fd_get interface. +
+cpg_join(3): Description of the cpg_join interface. +
+cpg_leave(3): Description of the cpg_leave interface. +
+cpg_mcast_joined(3): Description of the cpg_mcast_joined interface. +
+cpg_membership_get(3): Description of the cpg_membership_get interface. +