man/moira.3

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