man/moira.3

   1 .TH MOIRA 3 "8 Jan 1989"
   2 .FM mit
   3 .SH NAME
   4 mr_connect, mr_host, mr_auth, mr_disconnect, mr_noop, mr_access,
   5 mr_query, mr_do_update, mr_motd, mr_set_alternate_input,
   6 format_filesys_type, parse_filesys_type,
   7 canonicalize_hostname, strsave, strtrim, sq_create, sq_destroy,
   8 sq_get_data, sq_remove_data, sq_empty, sq_save_args, sq_save_data,
   9 sq_save_unique_data, sq_save_unique_string
  10 .SH SYNOPSIS
  11 .nf
  12 .nj
  13 .TP
  14 Protocol functions
  15 .B #include <moira.h>
  16
  17 .B int mr_connect(server);
  18 .B      char *server;
  19
  20 .B int mr_host(host, size);
  21 .B      char *server;
  22
  23 .B int mr_motd(motd);
  24 .B      char **motd;
  25
  26 .B int mr_auth(prog);
  27 .B      char *prog;
  28
  29 .B int mr_disconnect();
  30
  31 .B int mr_noop();
  32
  33 .B int mr_access(name, argc, argv);
  34 .B      char *name;
  35 .B      int argc;
  36 .B      char **argv;
  37
  38 .B int mr_query(name, argc, argv, callproc, callarg);
  39 .B      char *name;
  40 .B      int argc;
  41 .B      char **argv;
  42 .B      int (*callproc)(int, char **, char *);
  43 .B      char *callarg;
  44
  45 .B int mr_do_update();
  46
  47 .B int mr_set_alternate_input(fd, proc)
  48 .B      int fd;
  49 .B      void (*proc)();
  50 .TP
  51 Data manipulation
  52 .B char *format_filesys_type(fs_status);
  53 .B      char *fs_status;
  54
  55 .B char *parse_filesys_type(fs_type_name);
  56 .B      char *fs_type_name;
  57
  58 .B char *canonicalize_hostname(host);
  59 .B      char *host;
  60
  61 .B char *strsave(s);
  62 .B      char *s;
  63
  64 .B char *strtrim(s);
  65 .B      char *s;
  66 .TP
  67 Simple Queues
  68 .B struct save_queue *sq_create();
  69
  70 .B sq_destroy(sq);
  71 .B      struct save_queue *sq;
  72
  73 .B int sq_get_data(sq, data);
  74 .B      char **data;
  75
  76 .B int sq_remove_data(sq, data);
  77
  78 .B int sq_empty(sq);
  79
  80 .B sq_save_args(argc, argv, sq);
  81
  82 .B sq_save_data(sq, data);
  83
  84 .B sq_save_unique_data(sq, data);
  85
  86 .B sq_save_unique_string(sq, data);
  87 .fi
  88 .SH DESCRIPTION
  89 This library supports the Athena Service Management System protocol
  90 and related operations.  The library contains many routines beyond
  91 those described in this man page, but they are not intended to be used
  92 directly. Instead, they are called by the routines that are described.
  93
  94 Be sure to link your application against these libraries:
  95 -lmoira -lmrgdb -lcom_err -lkrb -ldes
  96 .TP
  97 Protocol functions
  98 All protocol routines return 0 on success, or a value from
  99 .I <mr_et.h>
 100 on failure.  An application should connect, check the motd in case the
 101 server is closed, authenticate, perform queries, then disconnect.
 102
 103 .B mr_connect
 104 establishes a connection with the Moira server.  The
 105 .I server
 106 specification is optional.  If present, it is of the form
 107 hostname:portname, where the portname can be looked up in
 108 .B /etc/services.
 109 If NULL or an empty string is passed as
 110 .I server,
 111 then the server will be found from the MOIRASERVER environment
 112 variable, the "moira" sloc entry in hesiod, or the compiled in
 113 default, in that order.
 114
 115 .B mr_host
 116 initializes
 117 .I host
 118 with the name of the host that the client is currently connected to.
 119
 120 .B mr_motd
 121 will check to see if the server is closed and if so, will retrieve an
 122 explanatory message (the so-called motd).  This routine will always
 123 return 0 if no error occurs.  *motd will be NULL if the server is
 124 functioning normally, or a pointer to a static string with the
 125 explanation if the server is down.
 126
 127 .B mr_auth
 128 authenticates an established connection using Kerberos.
 129 .I prog
 130 is the name of the program making the connection.  The program name
 131 and the kerberos principal name will be recorded with any changes made
 132 to the database through this connection.
 133
 134 .B mr_disconnect
 135 severs the connection with the Moira server.
 136
 137 .B mr_noop
 138 pings the Moira server through a "no operation" request, verifying that
 139 the connection is still working.
 140
 141 .B mr_access
 142 Verifies that the authenticated user has the necessary access to
 143 perform the query specified by
 144 .I name, argc,
 145 and
 146 .I argv.
 147
 148 .B mr_query
 149 performs a query.  This query may be a retrieval, append, delete, or
 150 update of the database.  Query
 151 .I name
 152 will be executed with the
 153 .I argc
 154 arguments specified in the string array
 155 .I argv.
 156 For each return tuple,
 157 .I callproc
 158 will be called with an
 159 .I argc, argv,
 160 and the value passed to
 161 .B mr_query
 162 as
 163 .I callarg.
 164
 165 .B mr_do_update
 166 triggers a DCM update immediately on the Moira server.
 167
 168 .B mr_set_alternate_input
 169 tells the Moira library that you want to allow some asynchronus
 170 actions while a query is being processed.  During query processing, if
 171 any data is available to be read on the specified file descriptor,
 172 then the specified function will be called to handle it.  For
 173 instance, calling mr_set_alternate_input with the connection to the X
 174 server and a routine which will dispatch X events will allow a toolkit
 175 application to handle mouse and expose events while a query is being
 176 processed.
 177 .TP
 178 Data manipulation
 179 .B format_filesys_type
 180 returns a user-displayable representation of the status bits on an NFS
 181 physical partition.
 182 .I fs_status
 183 is the ascii representation of the integer value of that field.
 184
 185 .B parse_filesys_type
 186 returns the numeric value of the filesystem type, given a string
 187 describing an NFS physical partition allocation type.  The returned
 188 value is a pointer to a static buffer containing the ascii
 189 representation of the integer value.
 190
 191 .B canonicalize_hostname
 192 attempts to update what is possibly the nickname for a host to its
 193 canonical form which is a fully specified, uppercase domain name.
 194 If the named host is in the namespace, it calls the nameserver to
 195 expand it and return the primary name of the host.  Otherwise, it just
 196 returns the argument.  It assumes that
 197 .I host
 198 was allocated using
 199 .I malloc(),
 200 and may be freed or realloc'ed before returning.  The returned value
 201 will be a malloc'ed value, possibly the same buffer as the argument.
 202
 203 .B strsave
 204 will malloc some memory and make a copy of
 205 .I s.
 206
 207 .B strtrim
 208 will trim whitespace off of both ends of the string
 209 .I s.
 210 The returned value will be a pointer into the same buffer
 211 .I s
 212 pointed to.
 213
 214 .TP
 215 Simple Queues
 216 .B sq_create
 217 will create an empty save_queue.
 218
 219 .B sq_destroy
 220 will free all of the memory contained in the queue structure
 221 .I sq.
 222 It will not attempt to free the elements.
 223
 224 .B sq_get_data
 225 will fill in
 226 .I data
 227 with the next piece of data in the queue.  If will return 0 if there
 228 is no more data in the queue.
 229
 230 .B sq_remove_data
 231 functions like sq_get_data except that any returned data is first
 232 removed from the queue.
 233
 234 .B sq_empty
 235 tests the length of the queue, returning non-zero if it is empty or
 236 zero if the queue contains data.
 237
 238 .B sq_save_args
 239 will make a copy of
 240 .I argv,
 241 null terminate it so that
 242 .I argc
 243 is not necessary, and save this value on the end of the queue
 244 .I sq.
 245
 246 .B sq_save_data
 247 saves
 248 .I data
 249 on the end of the queue
 250 .I sq.
 251
 252 .B sq_save_unique_data
 253 will save
 254 .I data
 255 on the queue if it does not already appear in the queue.  If it is
 256 already present, nothing is modified and no errors are returned.
 257 .B sq_save_unique_string
 258 is like
 259 .B sq_save_unique_data,
 260 except that it uses strcmp on the elements rather than comparing the
 261 addresses directly.
 262 .SH FILES
 263 /usr/athena/include/moira.h
 264 .br
 265 /usr/athena/include/mr_et.h
 266 .br
 267 /tmp/tkt###
 268 .SH "SEE ALSO"
 269 mrtest(8), The Moira section of the Athena Technical Plan
 270 .SH DIAGNOSTICS
 271 The error codes returned are those defined in <mr_et.h>, or
 272 <krb_et.h>.  They may be easily decoded using the com_err library.
 273 .SH RESTRICTIONS
 274 COPYRIGHT 1987,1988,1989 Massachusetts Institute of Technology