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