]>
Commit | Line | Data |
---|---|---|
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/include/moira.h | |
264 | .br | |
265 | /usr/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 |