man/moira.3

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