added new save_queue routines; punted protocol version number info;

additional info about how a server is chosen in sms_connect();

diff --git a/man/moira.3 b/man/moira.3
index 783696e4263cfbccedec9f61c879458a5d87cc0f..b312710e84ab9390f49baaa56b9b14a75e8f32b3 100644 (file)
--- a/man/moira.3
+++ b/man/moira.3
@@ -5,8 +5,8 @@ sms_connect, sms_host, sms_auth, sms_disconnect, sms_noop, sms_access,
 sms_query, sms_do_update, sms_motd, sms_set_alternate_input,
 format_filesys_type, parse_filesys_type,
 canonicalize_hostname, strsave, strtrim, sq_create, sq_destroy,
-sq_get_data, sq_save_args, sq_save_data, sq_save_unique_data,
-sq_save_unique_string
+sq_get_data, sq_remove_data, sq_empty, sq_save_args, sq_save_data,
+sq_save_unique_data, sq_save_unique_string
 .SH SYNOPSIS
 .nf
 .nj
@@ -14,8 +14,6 @@ sq_save_unique_string
 Protocol functions
 .B #include <sms.h>
 
-.B     extern int sending_version_no;
-
 .B int sms_connect(server);
 .B     char *server;
 
@@ -75,6 +73,10 @@ Simple Queues
 .B int sq_get_data(sq, data);
 .B     char **data;
 
+.B int sq_remove_data(sq, data);
+
+.B int sq_empty(sq);
+
 .B sq_save_args(argc, argv, sq);
 
 .B sq_save_data(sq, data);
@@ -98,21 +100,17 @@ All protocol routines return 0 on success, or a value from
 on failure.  An application should connect, check the motd in case the
 server is closed, authenticate, perform queries, then disconnect.
 
-.I sending_version_no
-may be set to
-.B SMS_VERSION_1
-or
-.B SMS_VERSION_2 
-to determine the version of the protocol that will be used.  It
-currently defaults to
-.B SMS_VERSION_2.
-
 .B sms_connect
 establishes a connection with the SMS server.  The
 .I server
-specification is of the form hostname:portname, where the portname can
-be looked up in 
+specification is optional.  If present, it is of the form
+hostname:portname, where the portname can be looked up in 
 .B /etc/services.
+If NULL or an empty string is passed as
+.I server,
+then the server will be found from the MOIRASERVER environment
+variable, the "moira" sloc entry in hesiod, or the compiled in
+default, in that order.
 
 .B sms_host
 initializes
@@ -213,10 +211,11 @@ The returned value will be a pointer into the same buffer
 .I s
 pointed to.
 
-.B sq_create
-will create an empty save_queue.
 .TP
 Simple Queues
+.B sq_create
+will create an empty save_queue.
+
 .B sq_destroy
 will free all of the memory contained in the queue structure
 .I sq.
@@ -228,6 +227,14 @@ will fill in
 with the next piece of data in the queue.  If will return 0 if there
 is no more data in the queue.
 
+.B sq_remove_data
+functions like sq_get_data except that any returned data is first
+removed from the queue.
+
+.B sq_empty
+tests the length of the queue, returning non-zero if it is empty or
+zero if the queue contains data.
+
 .B sq_save_args
 will make a copy of
 .I argv,
@@ -259,8 +266,7 @@ addresses directly.
 .br
 /tmp/tkt###
 .SH "SEE ALSO"
-smstest(8), The Service Management System section of the Athena
-Technical Plan
+mrtest(8), The Moira section of the Athena Technical Plan
 .SH DIAGNOSTICS
 The error codes returned are those defined in <sms_et.h>, or
 <krb_et.h>.  They may be easily decoded using the com_err library.