added sms_host() [qjb]

[moira.git] / man / moira.3

.TH SMS 3 "29 Nov 1988"
.FM mit
.SH NAME
sms_connect, sms_host, sms_auth, sms_disconnect, sms_noop, sms_access,
sms_query, sms_do_update, sms_motd, 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
.SH SYNOPSIS
.nf
.nj
.TP
Protocol functions
.B #include <sms.h>

.B	extern int sending_version_no;

.B int sms_connect(server);
.B	char *server;

.B int sms_host(host, size);
.B	char *server;

.B int sms_motd(motd);
.B	char **motd;

.B int sms_auth(prog);
.B	char *prog;

.B int sms_disconnect();

.B int sms_noop();

.B int sms_access(name, argc, argv);
.B	char *name;
.B	int argc;
.B	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 sms_do_update();
.TP
Data manipulation
.B char *format_filesys_type(fs_status);
.B	char *fs_status;

.B char *parse_filesys_type(fs_type_name);
.B	char *fs_type_name;

.B char *canonicalize_hostname(host);
.B	char *host;

.B char *strsave(s);
.B	char *s;

.B char *strtrim(s);
.B	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 sq_save_args(argc, argv, 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 Start_paging();

.B Stop_paging();

.B Start_menu(top_menu);
.B	Menu *top_menu;

.B Start_no_menu(top_menu);

.B Cleanup_menu();

.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;
.fi
.SH DESCRIPTION
This library supports the Athena Service Management System protocol
and related operations.  The library contains many routines beyond
those described in this man page, but they are not intended to be used
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.
.TP
Protocol functions
All protocol routines return 0 on success, or a value from 
.I <sms_et.h>
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 
.B /etc/services.

.B sms_host
initializes
.I host
with the name of the host that the client is currently connected to.

.B sms_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
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 sms_noop
pings the SMS server through a "no operation" request, verifying that
the connection is still working.

.B sms_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
performs a query.  This query may be a retrieval, append, delete, or
update of the database.  Query
.I name
will be executed with the
.I argc
arguments specified in the string array
.I argv.
For each return tuple,
.I callproc
will be called with an
.I argc, argv,
and the value passed to
.B sms_query
as
.I callarg.

.B sms_do_update
triggers a DCM update immediately on the SMS server.
.TP
Data manipulation
.B format_filesys_type
returns a user-displayable representation of the status bits on an NFS
physical partition.
.I fs_status
is the ascii representation of the integer value of that field.

.B parse_filesys_type
returns the numeric value of the filesystem type, given a string
describing an NFS physical partition allocation type.  The returned
value is a pointer to a static buffer containing the ascii
representation of the integer value.

.B canonicalize_hostname
attempts to update what is possibly the nickname for a host to its
canonical form which is a fully specified, uppercase domain name.
If the named host is in the namespace, it calls the nameserver to
expand it and return the primary name of the host.  Otherwise, it just
returns the argument.  It assumes that
.I host
was allocated using
.I malloc(),
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.
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_destroy
will free all of the memory contained in the queue structure
.I sq.
It will not attempt to free the elements.

.B sq_get_data
will fill in
.I data
with the next piece of data in the queue.  If will return 0 if there
is no more data in the queue.

.B sq_save_args
will make a copy of
.I argv,
null terminate it so that
.I argc
is not necessary, and save this value on the end of the queue
.I sq.

.B sq_save_data
saves
.I data
on the end of the queue
.I sq.

.B sq_save_unique_data
will save
.I data
on the queue if it does not already appear in the queue.  If it is
already present, nothing is modified and no errors are returned.
.B sq_save_unique_string
is like
.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
.br
/usr/include/sms_et.h
.br
/tmp/tkt###
.SH "SEE ALSO"
smstest(8), The Service Management System 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.
.SH RESTRICTIONS
COPYRIGHT 1987,1988 Massachusetts Institute of Technology