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