quorum: cleanup all man pages

sort and reference man pages in typical usage order

update some structures/defines

clean formatting to be consistent

Signed-off-by: Fabio M. Di Nitto <fdinitto@redhat.com>
Reviewed-by: Christine Caulfield <ccaulfie@redhat.com>

man/index.html

@@ -229,32 +229,44 @@
 
       <h3>QUORUM service</h3>
 
-      <a href="quorum_context_get.3.html">quorum_context_get(3)</a>:
-      Description of quorum_context_get interface.
+      <a href="quorum_overview.8.html">quorum_overview(8)</a>:
+      An overview of the quorum service
       <br>
 
-      <a href="quorum_context_set.3.html">quorum_context_set(3)</a>:
-      Description of quorum_context_set interface.
+      <a href="quorum_initialize.3.html">quorum_initialize(3)</a>:
+      Description of quorum_initialize interface.
       <br>
 
-      <a href="quorum_dispatch.3.html">quorum_dispatch(3)</a>:
-      Description of quorum_dispatch interface.
+      <a href="quorum_finalize.3.html">quorum_finalize(3)</a>:
+      Description of quorum_finalize interface.
+      <br>
+
+      <a href="quorum_getquorate.3.html">quorum_getquorate(3)</a>:
+      Description of quorum_getquorate interface.
+      <br>
+
+      <a href="quorum_trackstart.3.html">quorum_trackstart(3)</a>:
+      Description of quorum_trackstart interface.
+      <br>
+
+      <a href="quorum_trackstop.3.html">quorum_trackstop(3)</a>:
+      Description of quorum_trackstop interface.
       <br>
 
       <a href="quorum_fd_get.3.html">quorum_fd_get(3)</a>:
       Description of quorum_fd_get interface.
       <br>
 
-      <a href="quorum_finalize.3.html">quorum_finalize(3)</a>:
-      Description of quorum_finalize interface.
+      <a href="quorum_dispatch.3.html">quorum_dispatch(3)</a>:
+      Description of quorum_dispatch interface.
       <br>
 
-      <a href="quorum_getquorate.3.html">quorum_getquorate(3)</a>:
-      Description of quorum_getquorate interface.
+      <a href="quorum_context_set.3.html">quorum_context_set(3)</a>:
+      Description of quorum_context_set interface.
       <br>
 
-      <a href="quorum_initialize.3.html">quorum_initialize(3)</a>:
-      Description of quorum_initialize interface.
+      <a href="quorum_context_get.3.html">quorum_context_get(3)</a>:
+      Description of quorum_context_get interface.
       <br>
 
       <h3>VOTEQUORUM service</h3>

man/quorum_context_get.3.in

@@ -37,7 +37,7 @@ quorum_context_get \- Gets the context variable for a QUORUM instance
 .SH SYNOPSIS
 .B #include <corosync/quorum.h>
 .sp
-.BI "int quorum_context_get(quorum_handle_t " handle ", void **" context ");
+.BI "int quorum_context_get(quorum_handle_t " handle ", void **" context ");"
 .SH DESCRIPTION
 The
 .B quorum_context_get
@@ -49,8 +49,12 @@ This call returns the CS_OK value if successful, otherwise an error is returned.
 .SH ERRORS
 @COMMONIPCERRORS@
 .SH "SEE ALSO"
+.BR quorum_overview (8),
 .BR quorum_initialize (3),
 .BR quorum_finalize (3),
+.BR quorum_getquorate (3),
+.BR quorum_trackstart (3),
+.BR quorum_trackstop (3),
 .BR quorum_fd_get (3),
 .BR quorum_dispatch (3),
 .BR quorum_context_set (3),

man/quorum_context_set.3.in

@@ -37,7 +37,7 @@ quorum_context_set \- Sets the context variable for a QUORUM instance
 .SH SYNOPSIS
 .B #include <corosync/quorum.h>
 .sp
-.BI "int quorum_context_set(quorum_handle_t " handle ", void *" context ");
+.BI "int quorum_context_set(quorum_handle_t " handle ", void *" context ");"
 .SH DESCRIPTION
 The
 .B quorum_context_set
@@ -51,9 +51,13 @@ This call returns the CS_OK value if successful, otherwise an error is returned.
 .SH ERRORS
 @COMMONIPCERRORS@
 .SH "SEE ALSO"
+.BR quorum_overview (8),
 .BR quorum_initialize (3),
 .BR quorum_finalize (3),
+.BR quorum_getquorate (3),
+.BR quorum_trackstart (3),
+.BR quorum_trackstop (3),
 .BR quorum_fd_get (3),
 .BR quorum_dispatch (3),
-.BR quorum_context_get (3),
+.BR quorum_context_get (3)
 .PP

man/quorum_dispatch.3.in

@@ -37,7 +37,7 @@ quorum_dispatch \- Dispatches callbacks from the quorum service
 .SH SYNOPSIS
 .B #include <corosync/quorum.h>
 .sp
-.BI "int quorum_dispatch(quorum_handle_t " handle ", quorum_dispatch_t *" dispatch_types ");"
+.BI "int quorum_dispatch(quorum_handle_t " handle ", cs_dispatch_flags_t *" dispatch_types ");"
 .SH DESCRIPTION
 The
 .B quorum_dispatch
@@ -53,21 +53,14 @@ The
 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 {
-        CS_DISPATCH_ONE,
-        CS_DISPATCH_ALL,
-        CS_DISPATCH_BLOCKING
-} quorum_dispatch_t;
-.ta
+        CS_DISPATCH_ONE = 1,
+        CS_DISPATCH_ALL = 2,
+        CS_DISPATCH_BLOCKING = 3,
+        CS_DISPATCH_ONE_NONBLOCKING = 4
+} cs_dispatch_flags_t;
 .fi
-.RE
-.IP
-.PP
 .PP
 The dispatch values have the following meanings:
 .TP
@@ -92,8 +85,13 @@ This call returns the CS_OK value if successful, otherwise an error is returned.
 .SH ERRORS
 @COMMONIPCERRORS@
 .SH "SEE ALSO"
+.BR quorum_overview (8),
 .BR quorum_initialize (3),
 .BR quorum_finalize (3),
+.BR quorum_getquorate (3),
+.BR quorum_trackstart (3),
+.BR quorum_trackstop (3),
 .BR quorum_fd_get (3),
-
+.BR quorum_context_set (3),
+.BR quorum_context_get (3)
 .PP

man/quorum_fd_get.3.in

@@ -56,7 +56,13 @@ This call returns the CS_OK value if successful, otherwise an error is returned.
 .SH ERRORS
 @COMMONIPCERRORS@
 .SH "SEE ALSO"
+.BR quorum_overview (8),
 .BR quorum_initialize (3),
 .BR quorum_finalize (3),
+.BR quorum_getquorate (3),
+.BR quorum_trackstart (3),
+.BR quorum_trackstop (3),
 .BR quorum_dispatch (3),
+.BR quorum_context_set (3),
+.BR quorum_context_get (3)
 .PP

man/quorum_finalize.3.in

@@ -44,7 +44,8 @@ The
 function is used to close a connection to the quorum API.
 Once the connection is finalized, the handle may not be used again by applications.
 No more callbacks will be dispatched from the
-.B quorum_dispatch function.
+.B quorum_dispatch
+function.
 .PP
 .SH RETURN VALUE
 This call returns the CS_OK value if successful, otherwise an error is returned.
@@ -52,8 +53,13 @@ This call returns the CS_OK value if successful, otherwise an error is returned.
 .SH ERRORS
 @COMMONIPCERRORS@
 .SH "SEE ALSO"
+.BR quorum_overview (8),
 .BR quorum_initialize (3),
-.BR quorum_dispatch (3),
+.BR quorum_getquorate (3),
+.BR quorum_trackstart (3),
+.BR quorum_trackstop (3),
 .BR quorum_fd_get (3),
-
+.BR quorum_dispatch (3),
+.BR quorum_context_set (3),
+.BR quorum_context_get (3)
 .PP

man/quorum_getquorate.3.in

@@ -37,7 +37,7 @@ quorum_getquorate \- Gets the quorate status of the node.
 .SH SYNOPSIS
 .B #include <corosync/quorum.h>
 .sp
-.BI "int quorum_getquorate(quorum_handle_t " handle ", int *" quorate ");
+.BI "int quorum_getquorate(quorum_handle_t " handle ", int *" quorate ");"
 .SH DESCRIPTION
 The
 .B quorum_getquorate
@@ -49,6 +49,13 @@ This call returns the CS_OK value if successful, otherwise an error is returned.
 .SH ERRORS
 @COMMONIPCERRORS@
 .SH "SEE ALSO"
+.BR quorum_overview (8),
 .BR quorum_initialize (3),
 .BR quorum_finalize (3),
+.BR quorum_trackstart (3),
+.BR quorum_trackstop (3),
+.BR quorum_fd_get (3),
+.BR quorum_dispatch (3),
+.BR quorum_context_set (3),
+.BR quorum_context_get (3)
 .PP

man/quorum_initialize.3.in

@@ -37,7 +37,7 @@ quorum_initialize \- Create a new connection to the Quorum service
 .SH SYNOPSIS
 .B #include <corosync/quorum.h>
 .sp
-.BI "int quorum_initialize(quorum_handle_t *" handle ", quorum_callbacks_t *" callbacks ", uint32_t *" quorum_type ");
+.BI "int quorum_initialize(quorum_handle_t *" handle ", quorum_callbacks_t *" callbacks ", uint32_t *" quorum_type ");"
 .SH DESCRIPTION
 The
 .B quorum_initialize
@@ -55,6 +55,7 @@ Every time the voting configuraton changes (eg a node joins or leave the cluster
 the callback is called.
 The callback function is described by the following type definitions:
 
+.nf
 typedef void (*quorum_notification_fn_t) (
         quorum_handle_t handle,
         uint32_t quorate,
@@ -62,45 +63,26 @@ typedef void (*quorum_notification_fn_t) (
         uint32_t view_list_entries,
         uint32_t *view_list
         );
-
-.ta
 .fi
-.RE
-.IP
-.PP
 .PP
 The
 .I callbacks
 argument is of the type:
-.IP
-.RS
-.ne 18
+
 .nf
-.PP
 typedef struct {
         quorum_notification_fn_t quorum_notify_fn;
 } quorum_callbacks_t;
-
-.ta
 .fi
-.RE
-.IP
 .PP
 The
 .I quorum_type
 argument is set to:
-.IP
-.RS
-.ne 18
+
 .nf
-.PP
 #define QUORUM_FREE     0
 #define QUORUM_SET      1
-
-.ta
 .fi
-.RE
-.IP
 .PP
 .I QUORUM_FREE
 value means that no quorum algorithm is loaded and that no callbacks will take place.
@@ -119,7 +101,13 @@ This call returns the CS_OK value if successful, otherwise an error is returned.
 .SH ERRORS
 @COMMONIPCERRORS@
 .SH "SEE ALSO"
+.BR quorum_overview (8),
 .BR quorum_finalize (3),
+.BR quorum_getquorate (3),
+.BR quorum_trackstart (3),
+.BR quorum_trackstop (3),
 .BR quorum_fd_get (3),
 .BR quorum_dispatch (3),
+.BR quorum_context_set (3),
+.BR quorum_context_get (3)
 .PP

man/quorum_overview.8

@@ -38,7 +38,8 @@ quorum_overview \- Quorum Library Overview
 .SH OVERVIEW
 The quorum library is delivered with the corosync project. It is the external interface to
 the quorum service. This service is loaded into all nodes in a corosync cluster and track
-the quorate status of a node.
+the quorum status of a node. In order for quorum service to be useful, a quorum provider
+must be configured.
 .PP
 The library provides a mechanism to:
 .PP
@@ -49,18 +50,15 @@ The library provides a mechanism to:
 No known bugs at the time of writing. The authors are from outerspace. Deal with it.
 .SH "SEE ALSO"
 .BR corosync-quorumtool (8),
+.BR corosync.conf (5),
 .BR votequorum (5),
-.BR votequorum_context_get (3),
-.BR votequorum_context_set (3),
-.BR votequorum_dispatch (3),
-.BR votequorum_fd_get (3),
-.BR votequorum_finalize (3),
-.BR votequorum_getinfo (3),
-.BR votequorum_initialize (3),
-.BR votequorum_qdevice_getinfo (3),
-.BR votequorum_qdevice_poll (3),
-.BR votequorum_qdevice_register (3),
-.BR votequorum_qdevice_unregister (3),
-.BR votequorum_setexpected (3),
-.BR votequorum_setvotes (3)
+.BR quorum_initialize (3),
+.BR quorum_finalize (3),
+.BR quorum_getquorate (3),
+.BR quorum_trackstart (3),
+.BR quorum_trackstop (3),
+.BR quorum_fd_get (3),
+.BR quorum_dispatch (3),
+.BR quorum_context_set (3),
+.BR quorum_context_get (3)
 .PP

man/quorum_trackstart.3.in

@@ -37,7 +37,7 @@ quorum_trackstart \- Enable callbacks notification.
 .SH SYNOPSIS
 .B #include <corosync/quorum.h>
 .sp
-.BI "int quorum_trackstart(quorum_handle_t *" handle ", unsigned int " flags ");
+.BI "int quorum_trackstart(quorum_handle_t *" handle ", unsigned int " flags ");"
 .SH DESCRIPTION
 The
 .B quorum_trackstart
@@ -50,15 +50,28 @@ The notification is dispatched via
 .B quorum_dispatch()
 function that will execute the callback.
 .PP
+The 
+.I flags
+argument is defined by one or more of the following values and values can be bitwise-or'd
+
+.nf
+#define CS_TRACK_CURRENT      0x01
+#define CS_TRACK_CHANGES      0x02
+#define CS_TRACK_CHANGES_ONLY 0x04
+.fi
 .SH RETURN VALUE
 This call returns the CS_OK value if successful, otherwise an error is returned.
 .PP
 .SH ERRORS
 @COMMONIPCERRORS@
 .SH "SEE ALSO"
+.BR quorum_overview (8),
 .BR quorum_initialize (3),
 .BR quorum_finalize (3),
+.BR quorum_getquorate (3),
+.BR quorum_trackstop (3),
 .BR quorum_fd_get (3),
 .BR quorum_dispatch (3),
-.BR quorum_trackstop (3),
+.BR quorum_context_set (3),
+.BR quorum_context_get (3)
 .PP

man/quorum_trackstop.3.in

@@ -37,7 +37,7 @@ quorum_trackstop \- Disable callbacks notification.
 .SH SYNOPSIS
 .B #include <corosync/quorum.h>
 .sp
-.BI "int quorum_trackstart(quorum_handle_t *" handle ");
+.BI "int quorum_trackstart(quorum_handle_t *" handle ");"
 .SH DESCRIPTION
 The
 .B quorum_trackstop
@@ -49,9 +49,13 @@ This call returns the CS_OK value if successful, otherwise an error is returned.
 .SH ERRORS
 @COMMONIPCERRORS@
 .SH "SEE ALSO"
+.BR quorum_overview (8),
 .BR quorum_initialize (3),
 .BR quorum_finalize (3),
+.BR quorum_getquorate (3),
+.BR quorum_trackstart (3),
 .BR quorum_fd_get (3),
 .BR quorum_dispatch (3),
-.BR quorum_trackstart (3),
+.BR quorum_context_set (3),
+.BR quorum_context_get (3)
 .PP