man/moira.3

   1 .TH SMS 3 "8 Jan 1989"
   2 .FM mit
   3 .SH NAME
   4 sms_connect, sms_host, sms_auth, sms_disconnect, sms_noop, sms_access,
   5 sms_query, sms_do_update, sms_motd, sms_set_alternate_input,
   6 format_filesys_type, parse_filesys_type,
   7 canonicalize_hostname, strsave, strtrim, sq_create, sq_destroy,
   8 sq_get_data, sq_save_args, sq_save_data, sq_save_unique_data,
   9 sq_save_unique_string
  10 .SH SYNOPSIS
  11 .nf
  12 .nj
  13 .TP
  14 Protocol functions
  15 .B #include <sms.h>
  16
  17 .B      extern int sending_version_no;
  18
  19 .B int sms_connect(server);
  20 .B      char *server;
  21
  22 .B int sms_host(host, size);
  23 .B      char *server;
  24
  25 .B int sms_motd(motd);
  26 .B      char **motd;
  27
  28 .B int sms_auth(prog);
  29 .B      char *prog;
  30
  31 .B int sms_disconnect();
  32
  33 .B int sms_noop();
  34
  35 .B int sms_access(name, argc, argv);
  36 .B      char *name;
  37 .B      int argc;
  38 .B      char **argv;
  39
  40 .B int sms_query(name, argc, argv, callproc, callarg);
  41 .B      char *name;
  42 .B      int argc;
  43 .B      char **argv;
  44 .B      int (*callproc)(int, char **, char *);
  45 .B      char *callarg;
  46
  47 .B int sms_do_update();
  48
  49 .B int sms_set_alternate_input(fd, proc)
  50 .B      int fd;
  51 .B      void (*proc)();
  52 .TP
  53 Data manipulation
  54 .B char *format_filesys_type(fs_status);
  55 .B      char *fs_status;
  56
  57 .B char *parse_filesys_type(fs_type_name);
  58 .B      char *fs_type_name;
  59
  60 .B char *canonicalize_hostname(host);
  61 .B      char *host;
  62
  63 .B char *strsave(s);
  64 .B      char *s;
  65
  66 .B char *strtrim(s);
  67 .B      char *s;
  68 .TP
  69 Simple Queues
  70 .B struct save_queue *sq_create();
  71
  72 .B sq_destroy(sq);
  73 .B      struct save_queue *sq;
  74
  75 .B int sq_get_data(sq, data);
  76 .B      char **data;
  77
  78 .B sq_save_args(argc, argv, sq);
  79
  80 .B sq_save_data(sq, data);
  81
  82 .B sq_save_unique_data(sq, data);
  83
  84 .B sq_save_unique_string(sq, data);
  85 .fi
  86 .SH DESCRIPTION
  87 This library supports the Athena Service Management System protocol
  88 and related operations.  The library contains many routines beyond
  89 those described in this man page, but they are not intended to be used
  90 directly. Instead, they are called by the routines that are described.
  91
  92 Be sure to link your application against these libraries:
  93 -lsms -lsmsgdb -lcom_err -lkrb -ldes
  94 .TP
  95 Protocol functions
  96 All protocol routines return 0 on success, or a value from
  97 .I <sms_et.h>
  98 on failure.  An application should connect, check the motd in case the
  99 server is closed, authenticate, perform queries, then disconnect.
 100
 101 .I sending_version_no
 102 may be set to
 103 .B SMS_VERSION_1
 104 or
 105 .B SMS_VERSION_2
 106 to determine the version of the protocol that will be used.  It
 107 currently defaults to
 108 .B SMS_VERSION_2.
 109
 110 .B sms_connect
 111 establishes a connection with the SMS server.  The
 112 .I server
 113 specification is of the form hostname:portname, where the portname can
 114 be looked up in
 115 .B /etc/services.
 116
 117 .B sms_host
 118 initializes
 119 .I host
 120 with the name of the host that the client is currently connected to.
 121
 122 .B sms_motd
 123 will check to see if the server is closed and if so, will retrieve an
 124 explanatory message (the so-called motd).  This routine will always
 125 return 0 if no error occurs.  *motd will be NULL if the server is
 126 functioning normally, or a pointer to a static string with the
 127 explanation if the server is down.
 128
 129 .B sms_auth
 130 authenticates an established connection using Kerberos.
 131 .I prog
 132 is the name of the program making the connection.  The program name
 133 and the kerberos principal name will be recorded with any changes made
 134 to the database through this connection.
 135
 136 .B sms_disconnect
 137 severs the connection with the SMS server.
 138
 139 .B sms_noop
 140 pings the SMS server through a "no operation" request, verifying that
 141 the connection is still working.
 142
 143 .B sms_access
 144 Verifies that the authenticated user has the necessary access to
 145 perform the query specified by
 146 .I name, argc,
 147 and
 148 .I argv.
 149
 150 .B sms_query
 151 performs a query.  This query may be a retrieval, append, delete, or
 152 update of the database.  Query
 153 .I name
 154 will be executed with the
 155 .I argc
 156 arguments specified in the string array
 157 .I argv.
 158 For each return tuple,
 159 .I callproc
 160 will be called with an
 161 .I argc, argv,
 162 and the value passed to
 163 .B sms_query
 164 as
 165 .I callarg.
 166
 167 .B sms_do_update
 168 triggers a DCM update immediately on the SMS server.
 169
 170 .B sms_set_alternate_input
 171 tells the Moira library that you want to allow some asynchronus
 172 actions while a query is being processed.  During query processing, if
 173 any data is available to be read on the specified file descriptor,
 174 then the specified function will be called to handle it.  For
 175 instance, calling sms_set_alternate_input with the connection to the X
 176 server and a routine which will dispatch X events will allow a toolkit
 177 application to handle mouse and expose events while a query is being
 178 processed.
 179 .TP
 180 Data manipulation
 181 .B format_filesys_type
 182 returns a user-displayable representation of the status bits on an NFS
 183 physical partition.
 184 .I fs_status
 185 is the ascii representation of the integer value of that field.
 186
 187 .B parse_filesys_type
 188 returns the numeric value of the filesystem type, given a string
 189 describing an NFS physical partition allocation type.  The returned
 190 value is a pointer to a static buffer containing the ascii
 191 representation of the integer value.
 192
 193 .B canonicalize_hostname
 194 attempts to update what is possibly the nickname for a host to its
 195 canonical form which is a fully specified, uppercase domain name.
 196 If the named host is in the namespace, it calls the nameserver to
 197 expand it and return the primary name of the host.  Otherwise, it just
 198 returns the argument.  It assumes that
 199 .I host
 200 was allocated using
 201 .I malloc(),
 202 and may be freed or realloc'ed before returning.  The returned value
 203 will be a malloc'ed value, possibly the same buffer as the argument.
 204
 205 .B strsave
 206 will malloc some memory and make a copy of
 207 .I s.
 208
 209 .B strtrim
 210 will trim whitespace off of both ends of the string
 211 .I s.
 212 The returned value will be a pointer into the same buffer
 213 .I s
 214 pointed to.
 215
 216 .B sq_create
 217 will create an empty save_queue.
 218 .TP
 219 Simple Queues
 220 .B sq_destroy
 221 will free all of the memory contained in the queue structure
 222 .I sq.
 223 It will not attempt to free the elements.
 224
 225 .B sq_get_data
 226 will fill in
 227 .I data
 228 with the next piece of data in the queue.  If will return 0 if there
 229 is no more data in the queue.
 230
 231 .B sq_save_args
 232 will make a copy of
 233 .I argv,
 234 null terminate it so that
 235 .I argc
 236 is not necessary, and save this value on the end of the queue
 237 .I sq.
 238
 239 .B sq_save_data
 240 saves
 241 .I data
 242 on the end of the queue
 243 .I sq.
 244
 245 .B sq_save_unique_data
 246 will save
 247 .I data
 248 on the queue if it does not already appear in the queue.  If it is
 249 already present, nothing is modified and no errors are returned.
 250 .B sq_save_unique_string
 251 is like
 252 .B sq_save_unique_data,
 253 except that it uses strcmp on the elements rather than comparing the
 254 addresses directly.
 255 .SH FILES
 256 /usr/include/sms.h
 257 .br
 258 /usr/include/sms_et.h
 259 .br
 260 /tmp/tkt###
 261 .SH "SEE ALSO"
 262 smstest(8), The Service Management System section of the Athena
 263 Technical Plan
 264 .SH DIAGNOSTICS
 265 The error codes returned are those defined in <sms_et.h>, or
 266 <krb_et.h>.  They may be easily decoded using the com_err library.
 267 .SH RESTRICTIONS
 268 COPYRIGHT 1987,1988,1989 Massachusetts Institute of Technology