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