]>
Commit | Line | Data |
---|---|---|
2ad0a777 | 1 | .TH MOIRA 3 "8 Jan 1989" |
0a796925 | 2 | .FM mit |
3 | .SH NAME | |
2ad0a777 | 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, | |
7ad50c73 | 6 | format_filesys_type, parse_filesys_type, |
0a796925 | 7 | canonicalize_hostname, strsave, strtrim, sq_create, sq_destroy, |
2ed13b51 | 8 | sq_get_data, sq_remove_data, sq_empty, sq_save_args, sq_save_data, |
9 | sq_save_unique_data, sq_save_unique_string | |
0a796925 | 10 | .SH SYNOPSIS |
11 | .nf | |
12 | .nj | |
13 | .TP | |
14 | Protocol functions | |
ea0caf4a | 15 | .B |
16 | int mr_connect(char *server); | |
0a796925 | 17 | |
ea0caf4a | 18 | .B |
19 | int mr_host(char *host, int size); | |
0a796925 | 20 | |
ea0caf4a | 21 | .B |
22 | int mr_motd(char **motd); | |
5498c996 | 23 | |
ea0caf4a | 24 | .B |
25 | int mr_auth(char *prog); | |
ca170892 | 26 | |
ea0caf4a | 27 | .B |
28 | int mr_disconnect(void); | |
0a796925 | 29 | |
ea0caf4a | 30 | .B |
31 | int mr_noop(void); | |
0a796925 | 32 | |
ea0caf4a | 33 | .B |
34 | int mr_access(char *name, int argc, char **argv); | |
0a796925 | 35 | |
ea0caf4a | 36 | .B |
37 | int mr_query(char *name, int argc, char **argv, | |
38 | .B | |
39 | int (*callproc)(int, char **, void *), void *callarg); | |
0a796925 | 40 | |
0a796925 | 41 | .TP |
42 | Data manipulation | |
ea0caf4a | 43 | .B |
44 | char *format_filesys_type(char *fs_status); | |
0a796925 | 45 | |
ea0caf4a | 46 | .B |
47 | char *parse_filesys_type(char *fs_type_name); | |
0a796925 | 48 | |
ea0caf4a | 49 | .B |
50 | char *canonicalize_hostname(char *host); | |
0a796925 | 51 | |
ea0caf4a | 52 | .B |
53 | char *strtrim(char *s); | |
0a796925 | 54 | .TP |
55 | Simple Queues | |
ea0caf4a | 56 | .B |
57 | struct save_queue *sq_create(void); | |
0a796925 | 58 | |
ea0caf4a | 59 | .B |
60 | void sq_destroy(struct save_queue *sq); | |
0a796925 | 61 | |
ea0caf4a | 62 | .B |
63 | int sq_get_data(struct save_queue *sq, void *data); | |
0a796925 | 64 | |
ea0caf4a | 65 | .B |
66 | int sq_remove_data(struct save_queue *sq, void *data); | |
2ed13b51 | 67 | |
ea0caf4a | 68 | .B |
69 | int sq_empty(struct save_queue *sq); | |
2ed13b51 | 70 | |
ea0caf4a | 71 | .B |
72 | sq_save_args(int argc, char **argv, struct save_queue *sq); | |
0a796925 | 73 | |
ea0caf4a | 74 | .B |
75 | sq_save_data(struct save_queue *sq, void *data); | |
0a796925 | 76 | |
ea0caf4a | 77 | .B |
78 | sq_save_unique_data(struct save_queue *sq, void *data); | |
0a796925 | 79 | |
ea0caf4a | 80 | .B |
81 | sq_save_unique_string(struct save_queue *sq, char *data); | |
0a796925 | 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. | |
7726d871 | 88 | |
89 | Be sure to link your application against these libraries: | |
ea0caf4a | 90 | -lmoira -lkrb -ldes -lcom_err |
0a796925 | 91 | .TP |
92 | Protocol functions | |
a4a12338 | 93 | All protocol routines return 0 on success, or a value from |
2ad0a777 | 94 | .I <mr_et.h> |
ca170892 | 95 | on failure. An application should connect, check the motd in case the |
96 | server is closed, authenticate, perform queries, then disconnect. | |
0a796925 | 97 | |
2ad0a777 | 98 | .B mr_connect |
99 | establishes a connection with the Moira server. The | |
0a796925 | 100 | .I server |
2ed13b51 | 101 | specification is optional. If present, it is of the form |
102 | hostname:portname, where the portname can be looked up in | |
0a796925 | 103 | .B /etc/services. |
2ed13b51 | 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. | |
0a796925 | 109 | |
2ad0a777 | 110 | .B mr_host |
5498c996 | 111 | initializes |
112 | .I host | |
113 | with the name of the host that the client is currently connected to. | |
114 | ||
2ad0a777 | 115 | .B mr_motd |
ca170892 | 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 | ||
2ad0a777 | 122 | .B mr_auth |
0a796925 | 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 | ||
2ad0a777 | 129 | .B mr_disconnect |
130 | severs the connection with the Moira server. | |
0a796925 | 131 | |
2ad0a777 | 132 | .B mr_noop |
133 | pings the Moira server through a "no operation" request, verifying that | |
0a796925 | 134 | the connection is still working. |
135 | ||
2ad0a777 | 136 | .B mr_access |
0a796925 | 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 | ||
2ad0a777 | 143 | .B mr_query |
0a796925 | 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 | |
2ad0a777 | 156 | .B mr_query |
0a796925 | 157 | as |
158 | .I callarg. | |
159 | ||
0a796925 | 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 | ||
0a796925 | 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 | ||
0a796925 | 193 | .TP |
194 | Simple Queues | |
2ed13b51 | 195 | .B sq_create |
196 | will create an empty save_queue. | |
197 | ||
0a796925 | 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 | ||
2ed13b51 | 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 | ||
0a796925 | 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. | |
0a796925 | 241 | .SH FILES |
cb33d6a5 | 242 | /usr/athena/include/moira.h |
0a796925 | 243 | .br |
cb33d6a5 | 244 | /usr/athena/include/mr_et.h |
0a796925 | 245 | .br |
246 | /tmp/tkt### | |
247 | .SH "SEE ALSO" | |
2ed13b51 | 248 | mrtest(8), The Moira section of the Athena Technical Plan |
0a796925 | 249 | .SH DIAGNOSTICS |
2ad0a777 | 250 | The error codes returned are those defined in <mr_et.h>, or |
0a796925 | 251 | <krb_et.h>. They may be easily decoded using the com_err library. |
252 | .SH RESTRICTIONS | |
7ad50c73 | 253 | COPYRIGHT 1987,1988,1989 Massachusetts Institute of Technology |