]>
Commit | Line | Data |
---|---|---|
7ad50c73 | 1 | .TH SMS 3 "8 Jan 1989" |
0a796925 | 2 | .FM mit |
3 | .SH NAME | |
5498c996 | 4 | sms_connect, sms_host, sms_auth, sms_disconnect, sms_noop, sms_access, |
7ad50c73 | 5 | sms_query, sms_do_update, sms_motd, sms_set_alternate_input, |
6 | format_filesys_type, parse_filesys_type, | |
0a796925 | 7 | canonicalize_hostname, strsave, strtrim, sq_create, sq_destroy, |
8 | sq_get_data, sq_save_args, sq_save_data, sq_save_unique_data, | |
9 | sq_save_unique_string, Start_paging, Stop_paging, Start_menu, | |
10 | Start_no_menu, Cleanup_menu, Prompt_input, Password_input, Put_message | |
11 | .SH SYNOPSIS | |
12 | .nf | |
13 | .nj | |
14 | .TP | |
15 | Protocol functions | |
16 | .B #include <sms.h> | |
17 | ||
18 | .B extern int sending_version_no; | |
19 | ||
20 | .B int sms_connect(server); | |
21 | .B char *server; | |
22 | ||
5498c996 | 23 | .B int sms_host(host, size); |
24 | .B char *server; | |
25 | ||
ca170892 | 26 | .B int sms_motd(motd); |
27 | .B char **motd; | |
28 | ||
0a796925 | 29 | .B int sms_auth(prog); |
30 | .B char *prog; | |
31 | ||
32 | .B int sms_disconnect(); | |
33 | ||
34 | .B int sms_noop(); | |
35 | ||
36 | .B int sms_access(name, argc, argv); | |
37 | .B char *name; | |
38 | .B int argc; | |
39 | .B char **argv; | |
40 | ||
41 | .B int sms_query(name, argc, argv, callproc, callarg); | |
42 | .B char *name; | |
43 | .B int argc; | |
44 | .B char **argv; | |
45 | .B int (*callproc)(int, char **, char *); | |
46 | .B char *callarg; | |
47 | ||
48 | .B int sms_do_update(); | |
7ad50c73 | 49 | |
50 | .B int sms_set_alternate_input(fd, proc) | |
51 | .B int fd; | |
52 | .B void (*proc)(); | |
0a796925 | 53 | .TP |
54 | Data manipulation | |
55 | .B char *format_filesys_type(fs_status); | |
56 | .B char *fs_status; | |
57 | ||
58 | .B char *parse_filesys_type(fs_type_name); | |
59 | .B char *fs_type_name; | |
60 | ||
61 | .B char *canonicalize_hostname(host); | |
62 | .B char *host; | |
63 | ||
64 | .B char *strsave(s); | |
65 | .B char *s; | |
66 | ||
67 | .B char *strtrim(s); | |
68 | .B char *s; | |
69 | .TP | |
70 | Simple Queues | |
71 | .B struct save_queue *sq_create(); | |
72 | ||
73 | .B sq_destroy(sq); | |
74 | .B struct save_queue *sq; | |
75 | ||
76 | .B int sq_get_data(sq, data); | |
77 | .B char **data; | |
78 | ||
79 | .B sq_save_args(argc, argv, sq); | |
80 | ||
81 | .B sq_save_data(sq, data); | |
82 | ||
83 | .B sq_save_unique_data(sq, data); | |
84 | ||
85 | .B sq_save_unique_string(sq, data); | |
86 | .TP | |
87 | Menus | |
88 | .B #include <menu.h> | |
89 | .B char *whoami = argv[0]; | |
90 | ||
91 | .B Start_paging(); | |
92 | ||
93 | .B Stop_paging(); | |
94 | ||
95 | .B Start_menu(top_menu); | |
96 | .B Menu *top_menu; | |
97 | ||
98 | .B Start_no_menu(top_menu); | |
99 | ||
100 | .B Cleanup_menu(); | |
101 | ||
102 | .B Prompt_input(prompt, buf, buflen); | |
103 | .B char *prompt, buf; | |
104 | .B int buflen; | |
105 | ||
106 | .B Password_input(prompt, buf, buflen); | |
107 | ||
108 | .B Put_message(msg); | |
109 | .B char *msg; | |
110 | .fi | |
111 | .SH DESCRIPTION | |
112 | This library supports the Athena Service Management System protocol | |
113 | and related operations. The library contains many routines beyond | |
114 | those described in this man page, but they are not intended to be used | |
115 | directly. Instead, they are called by the routines that are described. | |
7726d871 | 116 | |
117 | Be sure to link your application against these libraries: | |
118 | -lsms -lsmsgdb -lcom_err -lkrb -ldes, and also curses if the menu are | |
119 | routines are to be used. | |
0a796925 | 120 | .TP |
121 | Protocol functions | |
a4a12338 | 122 | All protocol routines return 0 on success, or a value from |
0a796925 | 123 | .I <sms_et.h> |
ca170892 | 124 | on failure. An application should connect, check the motd in case the |
125 | server is closed, authenticate, perform queries, then disconnect. | |
0a796925 | 126 | |
127 | .I sending_version_no | |
128 | may be set to | |
129 | .B SMS_VERSION_1 | |
130 | or | |
131 | .B SMS_VERSION_2 | |
132 | to determine the version of the protocol that will be used. It | |
133 | currently defaults to | |
134 | .B SMS_VERSION_2. | |
135 | ||
136 | .B sms_connect | |
137 | establishes a connection with the SMS server. The | |
138 | .I server | |
139 | specification is of the form hostname:portname, where the portname can | |
140 | be looked up in | |
141 | .B /etc/services. | |
142 | ||
5498c996 | 143 | .B sms_host |
144 | initializes | |
145 | .I host | |
146 | with the name of the host that the client is currently connected to. | |
147 | ||
ca170892 | 148 | .B sms_motd |
149 | will check to see if the server is closed and if so, will retrieve an | |
150 | explanatory message (the so-called motd). This routine will always | |
151 | return 0 if no error occurs. *motd will be NULL if the server is | |
152 | functioning normally, or a pointer to a static string with the | |
153 | explanation if the server is down. | |
154 | ||
0a796925 | 155 | .B sms_auth |
156 | authenticates an established connection using Kerberos. | |
157 | .I prog | |
158 | is the name of the program making the connection. The program name | |
159 | and the kerberos principal name will be recorded with any changes made | |
160 | to the database through this connection. | |
161 | ||
162 | .B sms_disconnect | |
163 | severs the connection with the SMS server. | |
164 | ||
165 | .B sms_noop | |
166 | pings the SMS server through a "no operation" request, verifying that | |
167 | the connection is still working. | |
168 | ||
169 | .B sms_access | |
170 | Verifies that the authenticated user has the necessary access to | |
171 | perform the query specified by | |
172 | .I name, argc, | |
173 | and | |
174 | .I argv. | |
175 | ||
176 | .B sms_query | |
177 | performs a query. This query may be a retrieval, append, delete, or | |
178 | update of the database. Query | |
179 | .I name | |
180 | will be executed with the | |
181 | .I argc | |
182 | arguments specified in the string array | |
183 | .I argv. | |
184 | For each return tuple, | |
185 | .I callproc | |
186 | will be called with an | |
187 | .I argc, argv, | |
188 | and the value passed to | |
189 | .B sms_query | |
190 | as | |
191 | .I callarg. | |
192 | ||
193 | .B sms_do_update | |
194 | triggers a DCM update immediately on the SMS server. | |
7ad50c73 | 195 | |
196 | .B sms_set_alternate_input | |
197 | tells the Moira library that you want to allow some asynchronus | |
198 | actions while a query is being processed. During query processing, if | |
199 | any data is available to be read on the specified file descriptor, | |
200 | then the specified function will be called to handle it. For | |
201 | instance, calling sms_set_alternate_input with the connection to the X | |
202 | server and a routine which will dispatch X events will allow a toolkit | |
203 | application to handle mouse and expose events while a query is being | |
204 | processed. | |
0a796925 | 205 | .TP |
206 | Data manipulation | |
207 | .B format_filesys_type | |
208 | returns a user-displayable representation of the status bits on an NFS | |
209 | physical partition. | |
210 | .I fs_status | |
211 | is the ascii representation of the integer value of that field. | |
212 | ||
213 | .B parse_filesys_type | |
214 | returns the numeric value of the filesystem type, given a string | |
215 | describing an NFS physical partition allocation type. The returned | |
216 | value is a pointer to a static buffer containing the ascii | |
217 | representation of the integer value. | |
218 | ||
219 | .B canonicalize_hostname | |
220 | attempts to update what is possibly the nickname for a host to its | |
221 | canonical form which is a fully specified, uppercase domain name. | |
222 | If the named host is in the namespace, it calls the nameserver to | |
223 | expand it and return the primary name of the host. Otherwise, it just | |
224 | returns the argument. It assumes that | |
225 | .I host | |
226 | was allocated using | |
227 | .I malloc(), | |
228 | and may be freed or realloc'ed before returning. The returned value | |
229 | will be a malloc'ed value, possibly the same buffer as the argument. | |
230 | ||
231 | .B strsave | |
232 | will malloc some memory and make a copy of | |
233 | .I s. | |
234 | ||
235 | .B strtrim | |
236 | will trim whitespace off of both ends of the string | |
237 | .I s. | |
238 | The returned value will be a pointer into the same buffer | |
239 | .I s | |
240 | pointed to. | |
241 | ||
242 | .B sq_create | |
243 | will create an empty save_queue. | |
244 | .TP | |
245 | Simple Queues | |
246 | .B sq_destroy | |
247 | will free all of the memory contained in the queue structure | |
248 | .I sq. | |
249 | It will not attempt to free the elements. | |
250 | ||
251 | .B sq_get_data | |
252 | will fill in | |
253 | .I data | |
254 | with the next piece of data in the queue. If will return 0 if there | |
255 | is no more data in the queue. | |
256 | ||
257 | .B sq_save_args | |
258 | will make a copy of | |
259 | .I argv, | |
260 | null terminate it so that | |
261 | .I argc | |
262 | is not necessary, and save this value on the end of the queue | |
263 | .I sq. | |
264 | ||
265 | .B sq_save_data | |
266 | saves | |
267 | .I data | |
268 | on the end of the queue | |
269 | .I sq. | |
270 | ||
271 | .B sq_save_unique_data | |
272 | will save | |
273 | .I data | |
274 | on the queue if it does not already appear in the queue. If it is | |
275 | already present, nothing is modified and no errors are returned. | |
276 | .B sq_save_unique_string | |
277 | is like | |
278 | .B sq_save_unique_data, | |
279 | except that it uses strcmp on the elements rather than comparing the | |
280 | addresses directly. | |
281 | .TP | |
282 | Menus | |
283 | The menu package requires that the string | |
284 | .B whoami | |
285 | be defined. It is usually set to argv[0] of the program. | |
286 | ||
287 | .B Start_paging | |
288 | initializes menu package and sets up the screen. | |
289 | ||
290 | .B Stop_paging | |
291 | resets the screen to normal mode. This must be done before the | |
292 | program exits to put the tty back into a sane mode. | |
293 | ||
294 | .B Start_menu | |
295 | starts interpreting menus with | |
296 | .I top_menu, | |
297 | giving the menu package complete control of the screen. | |
298 | .B Start_paging | |
299 | must have been called first. | |
300 | ||
301 | .B Start_no_menu | |
302 | starts interpreting menus, but does not entirely give up control of | |
303 | the screen. The menu package will treat the tty as a printing | |
304 | terminal. | |
305 | ||
306 | .B Cleanup_menu | |
307 | aborts the menu package and returns the tty to sane modes. | |
308 | ||
309 | .B Prompt_input | |
a4a12338 | 310 | will get input from the user, using the dialogue window on the screen. |
0a796925 | 311 | It will first display |
312 | .I prompt, | |
313 | then read up to | |
314 | .I buflen | |
315 | bytes into the buffer | |
316 | .I buf. | |
317 | ||
318 | .B Password_input | |
319 | is like | |
320 | .I Prompt_input, | |
321 | except that the value the user types is not echoed. | |
322 | .B Put_message | |
323 | writes | |
324 | .I msg | |
325 | to the screen, appending a newline at the end. | |
326 | .SH FILES | |
327 | /usr/include/sms.h | |
328 | .br | |
329 | /usr/include/sms_et.h | |
330 | .br | |
331 | /tmp/tkt### | |
332 | .SH "SEE ALSO" | |
a4a12338 | 333 | smstest(8), The Service Management System section of the Athena |
0a796925 | 334 | Technical Plan |
335 | .SH DIAGNOSTICS | |
336 | The error codes returned are those defined in <sms_et.h>, or | |
337 | <krb_et.h>. They may be easily decoded using the com_err library. | |
338 | .SH RESTRICTIONS | |
7ad50c73 | 339 | COPYRIGHT 1987,1988,1989 Massachusetts Institute of Technology |