← Back to branch summary

~ubuntu-branches/ubuntu/trusty/tla/trusty

« back to all changes in this revision

Viewing changes to src/docs-hackerlab/texi/url-socket.texi

  • Committer: Bazaar Package Importer
  • Author(s): Andrew Suffield
  • Date: 2004-05-30 20:13:29 UTC
  • Revision ID: james.westby@ubuntu.com-20040530201329-mgovd2u99mkxi0hf
Tags: upstream-1.2
Import upstream version 1.2

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/docs-hackerlab/texi/url-socket.texi
 
1
@need 3200
 
2
 
 
3
@node A VU Handler for the URL Socket Scheme
 
4
@chapter A VU Handler for the URL Socket Scheme
 
5
 
 
6
These functions provide VU namespace handlers for file-names
 
7
that designate various kinds of sockets.  By using these handlers,
 
8
your programs can (almost) transparently handle filenames
 
9
like:
 
10
 
 
11
@example
 
12
@group
 
13
     inet://myserver.host.com:10000
 
14
@end group
 
15
@group
 
16
@end group
 
17
@end example
 
18
 
 
19
@noindent
 
20
or
 
21
 
 
22
@example
 
23
@group
 
24
     unix:/tmp/.X11-unix/X0
 
25
@end group
 
26
@group
 
27
@end group
 
28
@end example
 
29
 
 
30
Two kinds of sockets are available: @emph{server} sockets and @emph{client}
 
31
sockets.
 
32
 
 
33
 
 
34
@geindex server sockets
 
35
@dfn{server sockets} are created with @code{socket(2)}, @code{bind(2)}, and
 
36
@code{listen(2)}.  When @code{vu_open} is called, a call to @code{listen(2)} is
 
37
made and the client connection (if any) is returned.
 
38
 
 
39
 
 
40
@geindex client sockets
 
41
@dfn{client sockets} are created with @code{socket(2)}, @code{bind(2)}, and
 
42
@code{connect(2)}.
 
43
 
 
44
 
 
45
Sockets may be named in either the @code{unix} or @code{inet} domains.
 
46
 
 
47
 
 
48
The syntax of these URLs is described in the documentation for
 
49
@code{url_socket_push_client_handler} and
 
50
@code{url_socket_push_socket_handler}.
 
51
 
 
52
@sp 1
 
53
@need 1750
 
54
@noindent
 
55
@b{* Function} @code{url_socket_push_client_handler}@fuindex url_socket_push_client_handler
 
56
@*
 
57
@example
 
58
@group
 
59
void url_socket_push_client_handler (enum url_socket_domains domains,
 
60
                                     int default_port,
 
61
                                     int is_optional);
 
62
@end group
 
63
@group
 
64
@end group
 
65
@end example
 
66
 
 
67
Push a VU namespace handler for client sockets.
 
68
 
 
69
@example
 
70
@group
 
71
     Domains:                        File Name:
 
72
     ------------------------------------------------------------------
 
73
     url_socket_unix                 unix:$PATH
 
74
     url_socket_inet                 inet://$HOST[:$PORT]
 
75
     url_socket_inet_or_unix         unix:$PATH or inet://$HOST[:$PORT]
 
76
@end group
 
77
@group
 
78
@end group
 
79
@end example
 
80
 
 
81
Note that the @code{$PATH} of a unix domain socket is subject to @geindex ~
 
82
@dfn{~} expansion
 
83
using @code{file_name_tilde_expand}.
 
84
 
 
85
 
 
86
(See @strong{file_name_tilde_expand} in @ref{Home Directories}.)
 
87
 
 
88
 
 
89
@code{default_port} is used for internet-domain sockets.
 
90
 
 
91
 
 
92
If @code{is_optional} is @code{0}, the handler is immediately added to the VU namespace.
 
93
If @code{is_optional} is not @code{0}, the handler is added to the list of optional
 
94
handlers and may be enabled by @code{vu_enable_optional_name_handler}.
 
95
 
 
96
 
 
97
(See @strong{vu_enable_optional_name_handler} in @ref{Establishing VU Handlers}.)
 
98
 
 
99
@example
 
100
@group
 
101
     Domains:                        Optional Handler Name:
 
102
     ------------------------------------------------------------------
 
103
     url_socket_unix                 client/unix
 
104
     url_socket_inet                 client/inet
 
105
     url_socket_inet_or_unix         client/any
 
106
@end group
 
107
@group
 
108
@end group
 
109
@end example
 
110
@sp 1
 
111
@need 1750
 
112
@noindent
 
113
@b{* Function} @code{url_socket_push_socket_handler}@fuindex url_socket_push_socket_handler
 
114
@*
 
115
@example
 
116
@group
 
117
void url_socket_push_socket_handler 
 
118
     (enum url_socket_domains domains,
 
119
      int server_flags,
 
120
      int may_be_client,
 
121
      int only_server_url,
 
122
@end group
 
123
@group
 
124
      int default_port,
 
125
      int backlog,
 
126
@end group
 
127
@group
 
128
      url_socket_server_callback server_callback,
 
129
      url_socket_connect_callback connection_callback,
 
130
      url_socket_server_close_callback server_close_callback,
 
131
      void * closure,
 
132
      is_optional);
 
133
@end group
 
134
@group
 
135
@end group
 
136
@end example
 
137
 
 
138
Push a VU namespace handler for server sockets.  After this call, a
 
139
call to @code{vu_open} with a suitable file name will work by creating a
 
140
socket.
 
141
 
 
142
 
 
143
@code{server_flags} may be any bitwise combination of:
 
144
 
 
145
@example
 
146
@group
 
147
             O_NONBLOCK      # Don't block waiting for connections.
 
148
@end group
 
149
@group
 
150
@end group
 
151
@end example
 
152
 
 
153
There are two kinds of file name patterns: those that can be used
 
154
to name both clients and servers, and those that can only be used
 
155
to name servers:
 
156
 
 
157
@example
 
158
@group
 
159
     server only:                    client or server:
 
160
     -------------------------------------------------
 
161
     unix-server:$PATH               unix:$PATH
 
162
     inet-server://$HOST[:$PORT]     inet://$HOST[:$PORT]
 
163
@end group
 
164
@group
 
165
@end group
 
166
@end example
 
167
 
 
168
By default, both kinds of URL are accepted and interpreted as names
 
169
of server sockets.  Note that:
 
170
 
 
171
@example
 
172
@group
 
173
     `$PATH' of a unix domain socket is  subject to "~" expansion using 
 
174
     `file_name_tilde_expand'.
 
175
@end group
 
176
@group
 
177
@end group
 
178
@end example
 
179
@example
 
180
@group
 
181
     `$HOST' of an internet-domain socket may be `INADDR_LOOPBACK'.
 
182
     If the URL is the name of a server, `$HOST' may also be
 
183
     `INADDR_ANY'.  (See `inet(4)'.)
 
184
@end group
 
185
@group
 
186
@end group
 
187
@end example
 
188
@example
 
189
@group
 
190
     `$PORT' of an internet-domain server may be 0, meaning that the
 
191
     system should assign a port number which will be reported in 
 
192
     the server callback in the `server_addr' parameter (see below).
 
193
@end group
 
194
@group
 
195
@end group
 
196
@end example
 
197
 
 
198
If @code{may_be_client} is not @code{0}, then accept both kinds of URLs, but
 
199
interpret @geindex client or server
 
200
@dfn{client or server} URLs as naming client sockets (your
 
201
process will open a connection to some other server).
 
202
 
 
203
 
 
204
If @code{only_server_url} is not @code{0}, then accept @geindex server only
 
205
@dfn{server only} URLs, but
 
206
not @geindex client or server
 
207
@dfn{client or server} URLs.  In this case, @code{may_be_client} is
 
208
ignored.  This is especially useful in combination with
 
209
@code{url_socket_push_client_handler} and other calls to
 
210
@code{vu_push_name_handler}.
 
211
 
 
212
 
 
213
@code{default_port} is used when creating an internet-domain socket for
 
214
which the port number was not specified in the file-name.
 
215
 
 
216
 
 
217
@code{backlog} is used for the call to @code{listen(2)}.
 
218
 
 
219
 
 
220
@code{server_callback} is called when a new server socket has been
 
221
created successfully.  It's arguments are explained below.
 
222
 
 
223
 
 
224
@code{connect_callback} is called when a new connection has been
 
225
received.  It's arguments are explained below.
 
226
 
 
227
 
 
228
@code{server_close_callback} is called when the server descriptor
 
229
is closed.  It's arguments are explained below.
 
230
 
 
231
 
 
232
@code{closure} is an opaque value passed to the callback functions.
 
233
 
 
234
 
 
235
If @code{is_optional} is @code{0}, the handler is immediately added to the VU namespace.
 
236
If @code{is_optional} is non-0, the handler is added to the list of optional
 
237
handlers and may be enabled by @code{vu_enable_optional_name_handler}.
 
238
 
 
239
@example
 
240
@group
 
241
  domain(s) only_server_url may_be_client         Optional Handler Name
 
242
  --------------------------------------------------------------------
 
243
  unix            0               0               server/unix
 
244
  inet            0               0               server/inet
 
245
  inet_or_unix    0               0               server/any
 
246
@end group
 
247
@group
 
248
  unix            0               1               socket/unix
 
249
@end group
 
250
@group
 
251
  inet            0               1               socket/inet
 
252
  inet_or_unix    0               1               socket/any
 
253
  unix            1               *               socket/unix-server
 
254
  inet            1               *               socket/inet-server
 
255
  inet_or_unix    1               *               socket/any-server
 
256
@end group
 
257
@group
 
258
@end group
 
259
@end example
 
260
 
 
261
@strong{Calling Conventions for Callbacks}
 
262
 
 
263
@example
 
264
@group
 
265
 typedef void (*url_socket_server_callback) (char * path,
 
266
                                             int server_flags,
 
267
                                             int flags,
 
268
                                             int mode,
 
269
                                             int server_fd,
 
270
                                             struct sockaddr * server_addr,
 
271
                                             int server_addr_len,
 
272
                                             void * closure);
 
273
@end group
 
274
@group
 
275
@end group
 
276
@end example
 
277
@example
 
278
@group
 
279
     `path' is the file name that caused the server socket to
 
280
     be created.
 
281
@end group
 
282
@group
 
283
@end group
 
284
@end example
 
285
@example
 
286
@group
 
287
     `server_flags' is 0 or a bit-wise combination of `O_NONBLOCK'.
 
288
@end group
 
289
@group
 
290
@end group
 
291
@end example
 
292
@example
 
293
@group
 
294
     `flags' is the `flags' parameter passed to `vu_open', if this
 
295
     server socket was created by a call to `vu_open', 0 otherwise.
 
296
@end group
 
297
@group
 
298
@end group
 
299
@end example
 
300
@example
 
301
@group
 
302
     `mode' is the `mode' parameter passed to `vu_open', if this
 
303
     server socket was created by a call to `vu_open', 0 otherwise.
 
304
@end group
 
305
@group
 
306
@end group
 
307
@end example
 
308
@example
 
309
@group
 
310
     `server_fd' is the descriptor number of the server socket.
 
311
@end group
 
312
@group
 
313
@end group
 
314
@end example
 
315
@example
 
316
@group
 
317
     `server_addr' and `server_addr_len' is the address passed to
 
318
     `bind'.
 
319
@end group
 
320
@group
 
321
@end group
 
322
@end example
 
323
@example
 
324
@group
 
325
     `closure' is the `closure' argument passed to
 
326
     `url_socket_push_socket_handler'.
 
327
@end group
 
328
@group
 
329
@end group
 
330
@end example
 
331
@example
 
332
@group
 
333
 typedef void (*url_socket_connect_callback) 
 
334
             (char * path,
 
335
              int flags,
 
336
              int mode,
 
337
              int server_fd,
 
338
              int connection_fd,
 
339
              struct sockaddr * client_addr,
 
340
              int client_addr_len,
 
341
              void * closure);
 
342
@end group
 
343
@group
 
344
@end group
 
345
@end example
 
346
@example
 
347
@group
 
348
     `path' is the file name that caused the client connection to this
 
349
     server to be created.
 
350
@end group
 
351
@group
 
352
@end group
 
353
@end example
 
354
@example
 
355
@group
 
356
     `flags' is the `flags' parameter passed to `vu_open'.
 
357
@end group
 
358
@group
 
359
@end group
 
360
@end example
 
361
@example
 
362
@group
 
363
     `mode' is the `mode' parameter passed to `vu_open'.
 
364
@end group
 
365
@group
 
366
@end group
 
367
@end example
 
368
@example
 
369
@group
 
370
     `server_fd' is the descriptor number of the server socket.
 
371
@end group
 
372
@group
 
373
@end group
 
374
@end example
 
375
@example
 
376
@group
 
377
     `connection_fd' is the descriptor number of the client connection.
 
378
@end group
 
379
@group
 
380
@end group
 
381
@end example
 
382
@example
 
383
@group
 
384
     `client_addr' and `client_addr_len' is the address from `accept'.
 
385
@end group
 
386
@group
 
387
@end group
 
388
@end example
 
389
@example
 
390
@group
 
391
     `closure' is the `closure' argument passed to
 
392
     `url_socket_push_socket_handler'.
 
393
@end group
 
394
@group
 
395
@end group
 
396
@end example
 
397
@example
 
398
@group
 
399
 typedef void (*url_socket_server_close_callback) 
 
400
             (int server_fd,
 
401
              struct sockaddr * server_addr,
 
402
              int server_addr_len,
 
403
              void * closure);
 
404
@end group
 
405
@group
 
406
@end group
 
407
@end example
 
408
@example
 
409
@group
 
410
     `server_fd' is the descriptor number of the server socket.
 
411
@end group
 
412
@group
 
413
@end group
 
414
@end example
 
415
@example
 
416
@group
 
417
     `server_addr' and `server_addr_len' is the address passed to
 
418
     `bind'.
 
419
@end group
 
420
@group
 
421
@end group
 
422
@end example
 
423
@example
 
424
@group
 
425
     `closure' is the `closure' argument passed to
 
426
     `url_socket_push_socket_handler'.
 
427
@end group
 
428
@group
 
429
@end group
 
430
@end example
 
431
 
 
432
 
 
433