-.TH SMS 3 "29 Nov 1988"
+.TH MOIRA 3 "8 Jan 1989"
.FM mit
.SH NAME
-sms_connect, sms_auth, sms_disconnect, sms_noop, sms_access,
-sms_query, sms_do_update, format_filesys_type, parse_filesys_type,
+mr_connect, mr_host, mr_auth, mr_disconnect, mr_noop, mr_access,
+mr_query, mr_do_update, mr_motd, mr_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, Start_paging, Stop_paging, Start_menu,
-Start_no_menu, Cleanup_menu, Prompt_input, Password_input, Put_message
+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
.TP
Protocol functions
-.B #include <sms.h>
+.B
+int mr_connect(char *server);
-.B extern int sending_version_no;
+.B
+int mr_host(char *host, int size);
-.B int sms_connect(server);
-.B char *server;
+.B
+int mr_motd(char **motd);
-.B int sms_auth(prog);
-.B char *prog;
+.B
+int mr_auth(char *prog);
-.B int sms_disconnect();
+.B
+int mr_disconnect(void);
-.B int sms_noop();
+.B
+int mr_noop(void);
-.B int sms_access(name, argc, argv);
-.B char *name;
-.B int argc;
-.B char **argv;
+.B
+int mr_access(char *name, int argc, char **argv);
-.B int sms_query(name, argc, argv, callproc, callarg);
-.B char *name;
-.B int argc;
-.B char **argv;
-.B int (*callproc)(int, char **, char *);
-.B char *callarg;
+.B
+int mr_query(char *name, int argc, char **argv,
+.B
+ int (*callproc)(int, char **, void *), void *callarg);
-.B int sms_do_update();
.TP
Data manipulation
-.B char *format_filesys_type(fs_status);
-.B char *fs_status;
+.B
+char *format_filesys_type(char *fs_status);
-.B char *parse_filesys_type(fs_type_name);
-.B char *fs_type_name;
+.B
+char *parse_filesys_type(char *fs_type_name);
-.B char *canonicalize_hostname(host);
-.B char *host;
+.B
+char *canonicalize_hostname(char *host);
-.B char *strsave(s);
-.B char *s;
-
-.B char *strtrim(s);
-.B char *s;
+.B
+char *strtrim(char *s);
.TP
Simple Queues
-.B struct save_queue *sq_create();
-
-.B sq_destroy(sq);
-.B struct save_queue *sq;
-
-.B int sq_get_data(sq, data);
-.B char **data;
+.B
+struct save_queue *sq_create(void);
-.B sq_save_args(argc, argv, sq);
+.B
+void sq_destroy(struct save_queue *sq);
-.B sq_save_data(sq, data);
-
-.B sq_save_unique_data(sq, data);
-
-.B sq_save_unique_string(sq, data);
-.TP
-Menus
-.B #include <menu.h>
-.B char *whoami = argv[0];
+.B
+int sq_get_data(struct save_queue *sq, void *data);
-.B Start_paging();
+.B
+int sq_remove_data(struct save_queue *sq, void *data);
-.B Stop_paging();
+.B
+int sq_empty(struct save_queue *sq);
-.B Start_menu(top_menu);
-.B Menu *top_menu;
+.B
+sq_save_args(int argc, char **argv, struct save_queue *sq);
-.B Start_no_menu(top_menu);
+.B
+sq_save_data(struct save_queue *sq, void *data);
-.B Cleanup_menu();
+.B
+sq_save_unique_data(struct save_queue *sq, void *data);
-.B Prompt_input(prompt, buf, buflen);
-.B char *prompt, buf;
-.B int buflen;
-
-.B Password_input(prompt, buf, buflen);
-
-.B Put_message(msg);
-.B char *msg;
+.B
+sq_save_unique_string(struct save_queue *sq, char *data);
.fi
.SH DESCRIPTION
This library supports the Athena Service Management System protocol
directly. Instead, they are called by the routines that are described.
Be sure to link your application against these libraries:
--lsms -lsmsgdb -lcom_err -lkrb -ldes, and also curses if the menu are
-routines are to be used.
+-lmoira -lkrb -ldes -lcom_err
.TP
Protocol functions
All protocol routines return 0 on success, or a value from
-.I <sms_et.h>
-on failure. An application should connect, 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 <mr_et.h>
+on failure. An application should connect, check the motd in case the
+server is closed, authenticate, perform queries, then disconnect.
+
+.B mr_connect
+establishes a connection with the Moira 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 mr_host
+initializes
+.I host
+with the name of the host that the client is currently connected to.
+
+.B mr_motd
+will check to see if the server is closed and if so, will retrieve an
+explanatory message (the so-called motd). This routine will always
+return 0 if no error occurs. *motd will be NULL if the server is
+functioning normally, or a pointer to a static string with the
+explanation if the server is down.
-.B sms_auth
+.B mr_auth
authenticates an established connection using Kerberos.
.I prog
is the name of the program making the connection. The program name
and the kerberos principal name will be recorded with any changes made
to the database through this connection.
-.B sms_disconnect
-severs the connection with the SMS server.
+.B mr_disconnect
+severs the connection with the Moira server.
-.B sms_noop
-pings the SMS server through a "no operation" request, verifying that
+.B mr_noop
+pings the Moira server through a "no operation" request, verifying that
the connection is still working.
-.B sms_access
+.B mr_access
Verifies that the authenticated user has the necessary access to
perform the query specified by
.I name, argc,
and
.I argv.
-.B sms_query
+.B mr_query
performs a query. This query may be a retrieval, append, delete, or
update of the database. Query
.I name
will be called with an
.I argc, argv,
and the value passed to
-.B sms_query
+.B mr_query
as
.I callarg.
-.B sms_do_update
-triggers a DCM update immediately on the SMS server.
.TP
Data manipulation
.B format_filesys_type
and may be freed or realloc'ed before returning. The returned value
will be a malloc'ed value, possibly the same buffer as the argument.
-.B strsave
-will malloc some memory and make a copy of
-.I s.
-
.B strtrim
will trim whitespace off of both ends of the string
.I s.
.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.
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,
.B sq_save_unique_data,
except that it uses strcmp on the elements rather than comparing the
addresses directly.
-.TP
-Menus
-The menu package requires that the string
-.B whoami
-be defined. It is usually set to argv[0] of the program.
-
-.B Start_paging
-initializes menu package and sets up the screen.
-
-.B Stop_paging
-resets the screen to normal mode. This must be done before the
-program exits to put the tty back into a sane mode.
-
-.B Start_menu
-starts interpreting menus with
-.I top_menu,
-giving the menu package complete control of the screen.
-.B Start_paging
-must have been called first.
-
-.B Start_no_menu
-starts interpreting menus, but does not entirely give up control of
-the screen. The menu package will treat the tty as a printing
-terminal.
-
-.B Cleanup_menu
-aborts the menu package and returns the tty to sane modes.
-
-.B Prompt_input
-will get input from the user, using the dialogue window on the screen.
-It will first display
-.I prompt,
-then read up to
-.I buflen
-bytes into the buffer
-.I buf.
-
-.B Password_input
-is like
-.I Prompt_input,
-except that the value the user types is not echoed.
-.B Put_message
-writes
-.I msg
-to the screen, appending a newline at the end.
.SH FILES
-/usr/include/sms.h
+/usr/athena/include/moira.h
.br
-/usr/include/sms_et.h
+/usr/athena/include/mr_et.h
.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
+The error codes returned are those defined in <mr_et.h>, or
<krb_et.h>. They may be easily decoded using the com_err library.
.SH RESTRICTIONS
-COPYRIGHT 1987,1988 Massachusetts Institute of Technology
+COPYRIGHT 1987,1988,1989 Massachusetts Institute of Technology
andersk / moira.git / blobdiff