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