« back to all changes in this revision
Viewing changes to sa-1.2.2.orig/sa.pod
- browse files at revision 2
- compare with another revision
- download diff
- download tarball
- view history from revision 2
- Committer: Bazaar Package Importer
- Author(s): Raphael Bossek
- Date: 2004-11-29 10:55:45 UTC
- Revision ID: james.westby@ubuntu.com-20041129105545-djyxcyrguk6dl3yb
Tags: 1.2.2-1
Initial Release (Closes: #285820).
- files added:
- debian
- debian/patches
- sa-1.2.2.orig
added
removed
sa-1.2.2.orig/sa.pod
1
##
2
## OSSP sa - Socket Abstraction
3
## Copyright (c) 2001-2004 Ralf S. Engelschall <rse@engelschall.com>
4
## Copyright (c) 2001-2004 The OSSP Project <http://www.ossp.org/>
5
## Copyright (c) 2001-2004 Cable & Wireless <http://www.cw.com/>
6
##
7
## This file is part of OSSP sa, a socket abstraction library which
8
## can be found at http://www.ossp.org/pkg/lib/sa/.
9
##
10
## Permission to use, copy, modify, and distribute this software for
11
## any purpose with or without fee is hereby granted, provided that
12
## the above copyright notice and this permission notice appear in all
13
## copies.
14
##
15
## THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
16
## WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
17
## MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
18
## IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
19
## CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
20
## SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
21
## LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
22
## USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
23
## ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
24
## OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
25
## OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26
## SUCH DAMAGE.
27
##
28
## sa.pod: socket abstraction library manual page
29
##
30
31
=pod
32
33
=head1 NAME
34
35
B<OSSP sa> - Socket Abstraction
36
37
=head1 VERSION
38
39
B<OSSP sa SA_VERSION_STR>
40
41
=head1 SYNOPSIS
42
43
=over 4
44
45
=item B<Abstract Data Types>:
46
47
sa_rc_t,
48
sa_addr_t,
49
sa_t.
50
51
=item B<Address Object Operations>:
52
53
sa_addr_create,
54
sa_addr_destroy.
55
56
=item B<Address Operations>:
57
58
sa_addr_u2a,
59
sa_addr_s2a,
60
sa_addr_a2u,
61
sa_addr_a2s,
62
sa_addr_match.
63
64
=item B<Socket Object Operations>:
65
66
sa_create,
67
sa_destroy.
68
69
=item B<Socket Parameter Operations>:
70
71
sa_type,
72
sa_timeout,
73
sa_buffer,
74
sa_option,
75
sa_syscall.
76
77
=item B<Socket Connection Operations>:
78
79
sa_bind,
80
sa_connect,
81
sa_listen,
82
sa_accept,
83
sa_getremote,
84
sa_getlocal,
85
sa_shutdown.
86
87
=item B<Socket Input/Output Operations (Stream Communication)>:
88
89
sa_getfd,
90
sa_read,
91
sa_readln,
92
sa_write,
93
sa_writef,
94
sa_flush.
95
96
=item B<Socket Input/Output Operations (Datagram Communication)>:
97
98
sa_recv,
99
sa_send,
100
sa_sendf.
101
102
=item B<Socket Error Handling>:
103
104
sa_error.
105
106
=back
107
108
=head1 DESCRIPTION
109
110
B<OSSP sa> is an abstraction library for the Unix I<Socket> networking
111
application programming interface (API), featuring stream and datagram
112
oriented communication over I<Unix Domain> and I<Internet Domain> (TCP
113
and UDP) sockets.
114
115
It provides the following key features:
116
117
=over 4
118
119
=item B<Stand-Alone, Self-Contained, Embeddable>
120
121
Although there are various Open Source libraries available which provide
122
a similar abstraction approach, they all either lack important features
123
or unfortunately depend on other companion libraries. B<OSSP sa> fills
124
this gap by providing all important features (see following points) as a
125
stand-alone and fully self-contained library. This way B<OSSP sa> can be
126
trivially embedded as a sub-library into other libraries. It especially
127
provides additional support for namespace-safe embedding of its API in
128
order to avoid symbol conflicts (see C<SA_PREFIX> in F<sa.h>).
129
130
=item B<Address Abstraction>
131
132
Most of the ugliness in the Unix I<Socket> API is the necessity to
133
have to deal with the various address structures (C<struct sockaddr_xx>)
134
which exist because of both the different communication types and
135
addressing schemes. B<OSSP sa> fully hides this by providing an abstract
136
and opaque address type (C<sa_addr_t>) together with utility functions
137
which allow one to convert from the traditional C<struct sockaddr> or
138
URI specification to the C<sa_addr_t> and vice versa without having to
139
deal with special cases related to the underlying particular C<struct
140
sockaddr_xx>. B<OSSP sa> support I<Unix Domain> and both IPv4 and IPv6
141
I<Internet Domain> addressing.
142
143
=item B<Type Abstraction>
144
145
Some other subtle details in the Unix I<Socket> API make the life hard
146
in practice: C<socklen_t> and C<ssize_t>. These two types originally
147
were (and on some platforms still are) plain integers or unsigned
148
integers while POSIX later introduced own types for them (and even
149
revised these types after some time again). This is nasty, because
150
for 100% type-correct API usage (especially important on 64-bit
151
machines where pointers to different integer types make trouble), every
152
application has to check whether the newer types exists, and if not
153
provide own definitions which map to the still actually used integer
154
type on the underlying platform. B<OSSP sa> hides most of this in its
155
API and for C<socklen_t> provides a backward-compatibility definition.
156
Instead of C<ssize_t> it can use C<size_t> because B<OSSP sa> does not use
157
traditional Unix return code semantics.
158
159
=item B<I/O Timeouts>
160
161
Each I/O function in B<OSSP sa> is aware of timeouts (set by
162
sa_timeout(3)), i.e., all I/O operations return C<SA_ERR_TMT> if
163
the timeout expired before the I/O operation was able to succeed.
164
This allows one to easily program less-blocking network services.
165
B<OSSP sa> internally implements these timeouts either through the
166
C<SO_>{C<SND>,C<RCV>}C<TIMEO> feature on more modern I<Socket>
167
implementations or through traditional select(2). This way high
168
performance is achieved on modern platforms while the full functionality
169
still is available on older platforms.
170
171
=item B<I/O Stream Buffering>
172
173
If B<OSSP sa> is used for stream communication, internally all I/O
174
operations can be performed through input and/or output buffers (set
175
by sa_buffer(3)) for achieving higher I/O performance by doing I/O
176
operations on larger aggregated messages and with less required system
177
calls. Additionally if B<OSSP sa> is used for stream communication, for
178
convenience reasons line-oriented reading (sa_readln(3)) and formatted
179
writing (see sa_writef(3)) is provided, modelled after STDIO's fgets(3)
180
and fprintf(3). Both features fully leverage from the I/O buffering.
181
182
=back
183
184
=head1 DATA TYPES
185
186
B<OSSP sa> uses three data types in its API:
187
188
=over 4
189
190
=item B<sa_rc_t> (Return Code Type)
191
192
This is an exported enumerated integer type with the following possible
193
values:
194
195
SA_OK Everything Ok
196
SA_ERR_ARG Invalid Argument
197
SA_ERR_USE Invalid Use Or Context
198
SA_ERR_MEM Not Enough Memory
199
SA_ERR_MTC Matching Failed
200
SA_ERR_EOF End Of Communication
201
SA_ERR_TMT Communication Timeout
202
SA_ERR_SYS Operating System Error (see errno)
203
SA_ERR_IMP Implementation Not Available
204
SA_ERR_INT Internal Error
205
206
=item B<sa_addr_t> (Socket Address Abstraction Type)
207
208
This is an opaque data type representing a socket address.
209
Only pointers to this abstract data type are used in the API.
210
211
=item B<sa_t> (Socket Abstraction Type)
212
213
This is an opaque data type representing a socket.
214
Only pointers to this abstract data type are used in the API.
215
216
=back
217
218
=head1 FUNCTIONS
219
220
B<OSSP sa> provides a bunch of API functions, all modelled after the
221
same prototype:
222
223
C<sa_rc_t> B<sa_>I<name>C<(sa_>[C<addr_>]C<_t *,> ...C<)>
224
225
This means, every function returns C<sa_rc_t> to indicate its success
226
(C<SA_OK>) or failure (C<SA_ERR_>I<XXX>) by returning a return code (the
227
corresponding describing text can be determined by passing this return
228
code to sa_error(3)). Each function name starts with the common prefix
229
C<sa_> and receives a C<sa_t> (or C<sa_addr_t>) object handle on which
230
it operates as its first argument.
231
232
=head2 Address Object Operations
233
234
This API part provides operations for the creation and destruction of
235
address abstraction C<sa_addr_t>.
236
237
=over 4
238
239
=item C<sa_rc_t >B<sa_addr_create>C<(sa_addr_t **>I<saa>C<);>
240
241
Create a socket address abstraction object.
242
The object is stored in I<saa> on success.
243
244
Example: C<sa_addr_t *saa; sa_addr_create(&saa);>
245
246
=item C<sa_rc_t >B<sa_addr_destroy>C<(sa_addr_t *>I<saa>C<);>
247
248
Destroy a socket address abstraction object.
249
The object I<saa> is invalid after this call succeeded.
250
251
Example: C<sa_addr_destroy(saa);>
252
253
=back
254
255
=head2 Address Operations
256
257
This API part provides operations for working with the address
258
abstraction C<sa_addr_t>.
259
260
=over 4
261
262
=item C<sa_rc_t >B<sa_addr_u2a>C<(sa_addr_t *>I<saa>C<, const char *>I<uri>C<, ...);>
263
264
Import an address into by converting from an URI specification to the
265
corresponding address abstraction.
266
267
The supported syntax for I<uri> is: "C<unix:>I<path>" for I<Unix Domain>
268
addresses and "C<inet://>I<addr>C<:>I<port>[C<#>I<protocol>]" for
269
I<Internet Domain> addresses.
270
271
In the URI, I<path> can be an absolute or relative filesystem path
272
to an existing or not-existing file. I<addr> can be an IPv4 address
273
in dotted decimal notation ("C<127.0.0.1>"), an IPv6 address in
274
colon-separated (optionally abbreviated) hexadecimal notation ("C<::1>")
275
or a to-be-resolved hostname ("C<localhost.example.com>"). I<port> has
276
to be either a decimal port in the range C<1>...C<65535> or a port name
277
("C<smtp>"). If I<port> is specified as a name, it is resolved as a TCP
278
port by default. To force resolving a I<port> name via a particular
279
protocol, I<protocol> can be specified as either "C<tcp>" or "C<udp>".
280
281
The result is stored in I<saa> on success.
282
283
Example: C<sa_addr_u2a(saa, "inet://192.168.0.1:smtp");>
284
285
=item C<sa_rc_t >B<sa_addr_s2a>C<(sa_addr_t *>I<saa>C<, const struct sockaddr *>I<sabuf>C<, socklen_t >I<salen>C<);>
286
287
Import an address by converting from a traditional C<struct sockaddr>
288
object to the corresponding address abstraction.
289
290
The accepted addresses for I<sabuf> are: C<struct sockaddr_un>
291
(C<AF_LOCAL>), C<struct sockaddr_in> (C<AF_INET>) and C<struct
292
sockaddr_in6> (C<AF_INET6>). The I<salen> is the corresponding
293
C<sizeof(...)> of the particular underyling structure.
294
295
The result is stored in I<saa> on success.
296
297
Example: C<sockaddr_in in; sa_addr_s2a(saa, (struct sockaddr *)&in, (socklen_t)sizeof(in));>
298
299
=item C<sa_rc_t >B<sa_addr_a2u>C<(sa_addr_t *>I<saa>C<, char **>I<uri>C<);>
300
301
Export an address by converting from the address abstraction to the
302
corresponding URI specification.
303
304
The result is a string of the form "C<unix:>I<path>" for I<Unix
305
Domain> addresses and "C<inet://>I<addr>C<:>I<port>" for I<Internet
306
Domain> addresses. Notice that I<addr> and I<port> are returned in
307
numerical (unresolved) way. Additionally, because usually one cannot map
308
bidirectionally between TCP or UDP port names and the numerical value,
309
there is no distinction between TCP and UDP here.
310
311
The result is stored in I<uri> on success.
312
The caller has to free(3) the I<uri> buffer later.
313
314
Example: C<char *uri; sa_addr_a2u(saa, &uri);>
315
316
=item C<sa_rc_t >B<sa_addr_a2s>C<(sa_addr_t *>I<saa>C<, struct sockaddr **>I<sabuf>C<, socklen_t *>I<salen>C<);>
317
318
Export an address by converting from the address abstraction to the
319
corresponding traditional C<struct sockaddr> object.
320
321
The result is one of the following particular underlying address
322
structures: C<struct sockaddr_un> (C<AF_LOCAL>), C<struct sockaddr_in>
323
(C<AF_INET>) and C<struct sockaddr_in6> (C<AF_INET6>).
324
325
The result is stored in I<sabuf> and I<salen> on success.
326
The caller has to free(3) the I<sabuf> buffer later.
327
328
Example: C<struct sockaddr sabuf, socklen_t salen; sa_addr_a2s(saa, &sa, &salen);>
329
330
=item C<sa_rc_t >B<sa_addr_match>C<(sa_addr_t *>I<saa1>C<, sa_addr_t *>I<saa2>C<, size_t >I<prefixlen>C<);>
331
332
Match two address abstractions up to a specified prefix.
333
334
This compares the addresses I<saa1> and I<saa2> by only taking the
335
prefix part of length I<prefixlen> into account. I<prefixlen> is number
336
of filesystem path characters for I<Unix Domain> addresses and number
337
of bits for I<Internet Domain> addresses. In case of I<Internet Domain>
338
addresses, the addresses are matched in network byte order and the port
339
(counting as an additional bit/item of length 1) is virtually appended
340
to the address for matching. Specifying I<prefixlen> as C<-1> means
341
matching the whole address (but without the virtually appended port)
342
without having to know how long the underlying address representation
343
(length of path for Unix Domain addresses, 32+1 [IPv4] or 128+1 [IPv6]
344
for Internet Domain addresses) is. Specifying I<prefixlen> as C<-2> is
345
equal to C<-1> but additionally the port is matched, too.
346
347
This especially can be used to implement Access Control Lists (ACL)
348
without having to fiddle around with the underlying representation.
349
For this, make I<saa1> the to be checked address and I<saa2> plus
350
I<prefixlen> the ACL pattern as shown in the following example.
351
352
Example:
353
354
sa_addr_t *srv_sa;
355
sa_addr_t *clt_saa;
356
sa_t *clt_sa;
357
sa_addr_t *acl_saa;
358
char *acl_addr = "192.168.0.0";
359
int acl_len = 24;
360
...
361
sa_addr_u2a(&acl_saa, "inet://%s:0", acl_addr);
362
...
363
while (sa_accept(srv_sa, &clt_saa, &clt_sa) == SA_OK) {
364
if (sa_addr_match(clt_saa, acl_saa, acl_len) != SA_OK) {
365
/* connection refused */
366
...
367
sa_addr_destroy(clt_saa);
368
sa_destroy(clt_sa);
369
continue;
370
}
371
...
372
}
373
...
374
375
=back
376
377
=head2 Socket Object Operations
378
379
This API part provides operations for the creation and destruction of
380
socket abstraction C<sa_t>.
381
382
=over 4
383
384
=item C<sa_rc_t >B<sa_create>C<(sa_t **>I<sa>C<);>
385
386
Create a socket abstraction object.
387
The object is stored in I<sa> on success.
388
389
Example: C<sa_t *sa; sa_create(&sa);>
390
391
=item C<sa_rc_t >B<sa_destroy>C<(sa_t *>I<sa>C<);>
392
393
Destroy a socket abstraction object.
394
The object I<sa> is invalid after this call succeeded.
395
396
Example: C<sa_destroy(sa);>
397
398
=back
399
400
=head2 Socket Parameter Operations
401
402
This API part provides operations for parameterizing the socket
403
abstraction C<sa_t>.
404
405
=over 4
406
407
=item C<sa_rc_t >B<sa_type>C<(sa_t *>I<sa>C<, sa_type_t >I<type>C<);>
408
409
Assign a particular communication protocol type to the socket
410
abstraction object.
411
412
A socket can only be assigned a single protocol type at any time.
413
Nevertheless one can switch the type of a socket abstraction object at
414
any time in order to reuse it for a different communication. Just keep
415
in mind that switching the type will stop a still ongoing communication
416
by closing the underlying socket.
417
418
Possible values for I<type> are C<SA_TYPE_STREAM> (stream communication)
419
and C<SA_TYPE_DATAGRAM> (datagram communication). The default
420
communication protocol type is C<SA_TYPE_STREAM>.
421
422
Example: C<sa_type(sa, SA_TYPE_STREAM);>
423
424
=item C<sa_rc_t >B<sa_timeout>C<(sa_t *>I<sa>C<, sa_timeout_t >I<id>C<, long >I<sec>C<, long >I<usec>C<);>
425
426
Assign one or more communication timeouts to the socket abstraction
427
object.
428
429
Possible values for I<id> are: C<SA_TIMEOUT_ACCEPT> (affecting
430
sa_accept(3)), C<SA_TIMEOUT_CONNECT> (affecting sa_connect(3)),
431
C<SA_TIMEOUT_READ> (affecting sa_read(3), sa_readln(3) and sa_recv(3))
432
and C<SA_TIMEOUT_WRITE> (affecting sa_write(3), sa_writef(3),
433
sa_send(3), and sa_sendf(3)). Additionally you can set all four timeouts
434
at once by using C<SA_TIMEOUT_ALL>. The default is that no communication
435
timeouts are used which is equal to I<sec>=C<0>/I<usec>=C<0>.
436
437
Example: C<sa_timeout(sa, SA_TIMEOUT_ALL, 30, 0);>
438
439
=item C<sa_rc_t >B<sa_buffer>C<(sa_t *>I<sa>C<, sa_buffer_t >I<id>C<, size_t >I<size>C<);>
440
441
Assign I/O communication buffers to the socket abstraction object.
442
443
Possible values for I<id> are: C<SA_BUFFER_READ> (affecting sa_read(3)
444
and sa_readln(3)) and C<SA_BUFFER_WRITE> (affecting sa_write(3) and
445
sa_writef(3)). The default is that no communication buffers are used
446
which is equal to I<size>=C<0>.
447
448
Example: C<sa_buffer(sa, SA_BUFFER_READ, 16384);>
449
450
=item C<sa_rc_t >B<sa_option>C<(sa_t *>I<sa>C<, sa_option_t >I<id>C<, ...);>
451
452
Adjust various options of the socket abstraction object.
453
454
The adjusted option is controlled by I<id>. The number and type of the
455
expected following argument(s) are dependent on the particular option.
456
Currently the following options are implemented (option arguments in
457
parenthesis):
458
459
C<SA_OPTION_NAGLE> (C<int> I<yesno>) for enabling (I<yesno>=C<1>)
460
or disabling (I<yesno> == C<0>) Nagle's Algorithm (see RFC898 and
461
C<TCP_NODELAY> of setsockopt(2)).
462
463
C<SA_OPTION_LINGER> (C<int> I<amount>) for enabling (I<amount> ==
464
I<seconds> != C<0>) or disabling (I<amount> == C<0>) lingering on close
465
(see C<SO_LINGER> of setsockopt(2)). Notice: using I<seconds> E<gt> C<0>
466
results in a regular (maximum of I<seconds> lasting) lingering on close
467
while using I<seconds> E<lt> C<0> results in the special case of a TCP
468
RST based connection termination on close.
469
470
C<SA_OPTION_REUSEADDR> (C<int> I<yesno>) for enabling (I<yesno> ==
471
C<1>) or disabling (I<yesno> == C<0>) the reusability of the address on
472
binding via sa_bind(3) (see C<SO_REUSEADDR> of setsockopt(2)).
473
474
C<SA_OPTION_REUSEPORT> (C<int> I<yesno>) for enabling (I<yesno> == C<1>)
475
or disabling (I<yesno> == C<0>) the reusability of the port on binding
476
via sa_bind(3) (see C<SO_REUSEPORT> of setsockopt(2)).
477
478
C<SA_OPTION_NONBLOCK> (C<int> I<yesno>) for enabling (I<yesno> == C<1>)
479
or disabling (I<yesno> == C<0>) non-blocking I/O mode (see C<O_NONBLOCK>
480
of fcntl(2)).
481
482
Example: C<sa_option(sa, SA_OPTION_NONBLOCK, 1);>
483
484
=item C<sa_rc_t >B<sa_syscall>C<(sa_t *>I<sa>C<, sa_syscall_t >I<id>C<, void (*>I<fptr>C<)(), void *>I<fctx>C<);>
485
486
Divert I/O communication related system calls to user supplied callback
487
functions.
488
489
This allows you to override mostly all I/O related system calls B<OSSP
490
sa> internally performs while communicating. This can be used to adapt
491
B<OSSP sa> to different run-time environments and requirements without
492
having to change the source code. Usually this is used to divert the
493
system calls to the variants of a user-land multithreading facility like
494
B<GNU Pth>.
495
496
The function supplied as I<fptr> is required to fulfill the API of
497
the replaced system call, i.e., it has to have the same prototype (if
498
I<fctx> is C<NULL>). If I<fctx> is not C<NULL>, this prototype has to be
499
extended to accept an additional first argument of type C<void *> which
500
receives the value of I<fctx>. It is up to the callback function whether
501
to pass the call through to the replaced actual system call or not.
502
503
Possible values for I<id> are (expected prototypes behind I<fptr> are
504
given in parenthesis):
505
506
C<SA_SYSCALL_CONNECT>: "C<int (*)([void *,] int, const struct sockaddr
507
*, socklen_t)>", see connect(2).
508
509
C<SA_SYSCALL_ACCEPT>: "C<int (*)([void *,] int, struct sockaddr *,
510
socklen_t *)>", see accept(2).
511
512
C<SA_SYSCALL_SELECT>: "C<int (*)([void *,] int, fd_set *, fd_set *,
513
fd_set *, struct timeval *)>", see select(2).
514
515
C<SA_SYSCALL_READ>: "C<ssize_t (*)([void *,] int, void *, size_t)>", see
516
read(2).
517
518
C<SA_SYSCALL_WRITE>: "C<ssize_t (*)([void *,] int, const void *,
519
size_t)>", see write(2).
520
521
C<SA_SYSCALL_RECVFROM>: "C<ssize_t (*)([void *,] int, void *, size_t,
522
int, struct sockaddr *, socklen_t *)>", see recvfrom(2).
523
524
C<SA_SYSCALL_SENDTO>: "C<ssize_t (*)([void *,] int, const void *,
525
size_t, int, const struct sockaddr *, socklen_t)>", see sendto(2).
526
527
Example:
528
529
FILE *trace_fp = ...;
530
531
ssize_t
532
trace_read(void *ctx, int fd, void *buf, size_t len)
533
{
534
FILE *fp = (FILE *)ctx;
535
ssize_t rv;
536
int errno_saved;
537
538
rv = read(fd, buf, len);
539
errno_saved = errno;
540
fprintf(fp, "read(%d, %lx, %d) = %d\n",
541
fd, (long)buf, len, rv);
542
errno = errno_saved;
543
return rv;
544
}
545
546
sa_syscall(sa, SA_SC_READ, trace_read, trace_fp);
547
548
=back
549
550
=head2 Socket Connection Operations
551
552
This API part provides connection operations for stream-oriented data
553
communication through the socket abstraction C<sa_t>.
554
555
=over 4
556
557
=item C<sa_rc_t >B<sa_bind>C<(sa_t *>I<sa>C<, sa_addr_t *>I<laddr>C<);>
558
559
Bind socket abstraction object to a local protocol address.
560
561
This assigns the local protocol address I<laddr>. When a socket is
562
created, it exists in an address family space but has no protocol
563
address assigned. This call requests that I<laddr> be used as the local
564
address. For servers this is the address they later listen on (see
565
sa_listen(3)) for incoming connections, for clients this is the address
566
used for outgoing connections (see sa_connect(3)). Internally this
567
directly maps to bind(2).
568
569
Example: C<sa_bind(sa, laddr);>
570
571
=item C<sa_rc_t >B<sa_connect>C<(sa_t *>I<sa>C<, sa_addr_t *>I<raddr>C<);>
572
573
Initiate an outgoing connection on a socket abstraction object.
574
575
This performs a connect to the remote address I<raddr>. If the socket
576
is of type C<SA_TYPE_DATAGRAM>, this call specifies the peer with which
577
the socket is to be associated; this address is that to which datagrams
578
are to be sent, and the only address from which datagrams are to be
579
received. If the socket is of type C<SA_TYPE_STREAM>, this call attempts
580
to make a connection to the remote socket. Internally this directly maps
581
to connect(2).
582
583
Example: C<sa_connect(sa, raddr);>
584
585
=item C<sa_rc_t >B<sa_listen>C<(sa_t *>I<sa>C<, int >I<backlog>C<);>
586
587
Listen for incoming connections on a socket abstraction object.
588
589
A willingness to accept incoming connections and a queue limit for
590
incoming connections are specified by this call. The I<backlog> argument
591
defines the maximum length the queue of pending connections may grow to.
592
Internally this directly maps to listen(2).
593
594
Example: C<sa_listen(sa, 128);>
595
596
=item C<sa_rc_t >B<sa_accept>C<(sa_t *>I<sa>C<, sa_addr_t **>I<caddr>C<, sa_t **>I<csa>C<);>
597
598
Accept incoming connection on a socket abstraction object.
599
600
This accepts an incoming connection by extracting the first connection
601
request on the queue of pending connections. It creates a new socket
602
abstraction object (returned in I<csa>) and a new socket address
603
abstraction object (returned in I<caddr>) describing the connection. The
604
caller has to destroy these objects later. If no pending connections
605
are present on the queue, it blocks the caller until a connection is
606
present.
607
608
Example:
609
610
sa_addr_t *clt_saa;
611
sa_t *clt_sa;
612
...
613
while (sa_accept(srv_sa, &clt_saa, &clt_sa) == SA_OK) {
614
...
615
}
616
617
=item C<sa_rc_t >B<sa_getremote>C<(sa_t *>I<sa>C<, sa_addr_t **>I<raddr>C<);>
618
619
Get address abstraction of remote side of communication.
620
621
This determines the address of the communication peer and creates a new
622
socket address abstraction object (returned in I<raddr>) describing
623
the peer address. The application has to destroy I<raddr> later with
624
sa_addr_destroy(3). Internally this maps to getpeername(2).
625
626
Example: C<sa_addr_t *raddr; sa_getremote(sa, &raddr);>
627
628
=item C<sa_rc_t >B<sa_getlocal>C<(sa_t *>I<sa>C<, sa_addr_t **>I<laddr>C<);>
629
630
Get address abstraction of local side of communication.
631
632
This determines the address of the local communication side and
633
creates a new socket address abstraction object (returned in I<laddr>)
634
describing the local address. The application has to destroy I<laddr>
635
later with sa_addr_destroy(3). Internally this maps to getsockname(2).
636
637
Example: C<sa_addr_t *laddr; sa_getlocal(sa, &laddr);>
638
639
=item C<sa_rc_t >B<sa_shutdown>C<(sa_t *>I<sa>C<, char *>I<flags>C<);>
640
641
Shut down part of the full-duplex connection.
642
643
This performs a shut down of the connection described in I<sa>. The
644
flags string can be either "C<r>" (indicating the read channel of the
645
communication is shut down only), "C<w>" (indicating the write channel
646
of the communication is shut down only), or "C<rw>" (indicating both the
647
read and write channels of the communication are shut down). Internally
648
this directly maps to shutdown(2).
649
650
Example: C<sa_shutdown(sa, "w");>
651
652
=back
653
654
=head2 Socket Input/Output Operations (Stream Communication)
655
656
This API part provides I/O operations for stream-oriented data
657
communication through the socket abstraction C<sa_t>.
658
659
=over 4
660
661
=item C<sa_rc_t >B<sa_getfd>C<(sa_t *>I<sa>C<, int *>I<fd>C<);>
662
663
Get underlying socket filedescriptor.
664
665
This peeks into the underlying socket filedescriptor B<OSSP sa>
666
allocated internally for the communication. This can be used for
667
adjusting the socket communication (via fcntl(2), setsockopt(2), etc)
668
directly.
669
670
Think twice before using this, then think once more. After all that,
671
think again. With enough thought, the need for directly manipulating the
672
underlying socket can often be eliminated. At least remember that all
673
your direct socket operations fully by-pass B<OSSP sa> and this way can
674
leads to nasty side-effects.
675
676
Example: C<int fd; sa_getfd(sa, &fd);>
677
678
=item C<sa_rc_t >B<sa_read>C<(sa_t *>I<sa>C<, char *>I<buf>C<, size_t >I<buflen>C<, size_t *>I<bufdone>C<);>
679
680
Read a chunk of data from socket into own buffer.
681
682
This reads from the socket (optionally through the internal read buffer)
683
up to a maximum of I<buflen> bytes into buffer I<buf>. The actual number
684
of read bytes is stored in I<bufdone>. This internally maps to read(2).
685
686
Example: C<char buf[1024]; size_t n; sa_read(sa, buf, sizeof(buf), &n);>
687
688
=item C<sa_rc_t >B<sa_readln>C<(sa_t *>I<sa>C<, char *>I<buf>C<, size_t >I<buflen>C<, size_t *>I<bufdone>C<);>
689
690
Read a line of data from socket into own buffer.
691
692
This reads from the socket (optionally through the internal read buffer)
693
up to a maximum of I<buflen> bytes into buffer I<buf>, but only as long
694
as no line terminating newline character (0x0a) was found. The line
695
terminating newline character is stored in the buffer plus a (not
696
counted) terminating C<NUL> character ('C<\0>'), too. The actual
697
number of read bytes is stored in I<bufdone>. This internally maps to
698
sa_read(3).
699
700
Keep in mind that for efficiency reasons, line-oriented I/O usually
701
always should be performed with read buffer (see sa_option(3) and
702
C<SA_BUFFER_READ>). Without such a read buffer, the performance is
703
cruel, because single character read(2) operations would be performed on
704
the underlying socket.
705
706
Example: C<char buf[1024]; size_t n; sa_readln(sa, buf, sizeof(buf), &n);>
707
708
=item C<sa_rc_t >B<sa_write>C<(sa_t *>I<sa>C<, const char *>I<buf>C<, size_t >I<buflen>C<, size_t *>I<bufdone>C<);>
709
710
Write a chunk of data to socket from own buffer.
711
712
This writes to the socket (optionally through the internal write buffer)
713
I<buflen> bytes from buffer I<buf>. In case of a partial write, the
714
actual number of written bytes is stored in I<bufdone>. This internally
715
maps to write(2).
716
717
Example: C<sa_write(sa, cp, strlen(cp), NULL);>
718
719
=item C<sa_rc_t >B<sa_writef>C<(sa_t *>I<sa>C<, const char *>I<fmt>C<, ...);>
720
721
Write formatted data data to socket.
722
723
This formats a string according to the printf(3)-style format
724
specification I<fmt> and sends the result to the socket (optionally
725
through the internal write buffer). In case of a partial socket
726
write, the not written data of the formatted string is internally
727
discarded. Hence using a write buffer is strongly recommended here
728
(see sa_option(3) and C<SA_BUFFER_WRITE>). This internally maps to
729
sa_write(3).
730
731
The underlying string formatting engine is just a minimal one and for
732
security and independence reasons intentionally not directly based on
733
s[n]printf(3). It understands only the following format specifications:
734
"C<%%>", "C<%c>" (C<char>), "C<%s>" (C<char *>) and "C<%d>" (C<int>)
735
without any precision and padding possibilities. It is intended for
736
minimal formatting only. If you need more sophisticated formatting, you
737
have to format first into an own buffer via s[n]printf(3) and then write
738
this to the socket via sa_write(3) instead.
739
740
Example: C<sa_writef(sa, "%s=%d\n", cp, i);>
741
742
=item C<sa_rc_t >B<sa_flush>C<(sa_t *>I<sa>C<);>
743
744
Flush still pending outgoing data to socket.
745
746
This writes all still pending outgoing data for the internal write
747
buffer (see sa_option(3) and C<SA_BUFFER_WRITE>) to the socket. This
748
internally maps to write(2).
749
750
Example: C<sa_flush(sa);>
751
752
=back
753
754
=head2 Socket Input/Output Operations (Datagram Communication)
755
756
This API part provides I/O operations for datagram-oriented data
757
communication through the socket abstraction C<sa_t>.
758
759
=over 4
760
761
=item C<sa_rc_t >B<sa_recv>C<(sa_t *>I<sa>C<, sa_addr_t **>I<raddr>C<, char *>I<buf>C<, size_t >I<buflen>C<, size_t *>I<bufdone>C<);>
762
763
Receive a chunk of data from remote address via socket into own buffer.
764
765
This receives from the remote address specified in I<raddr> via the
766
socket up to a maximum of I<buflen> bytes into buffer I<buf>. The actual
767
number of received bytes is stored in I<bufdone>. This internally maps
768
to recvfrom(2).
769
770
Example: C<char buf[1024]; size_t n; sa_recv(sa, buf, sizeof(buf), &n, saa);>
771
772
=item C<sa_rc_t >B<sa_send>C<(sa_t *>I<sa>C<, sa_addr_t *>I<raddr>C<, const char *>I<buf>C<, size_t >I<buflen>C<, size_t *>I<bufdone>C<);>
773
774
Send a chunk of data to remote address via socket from own buffer.
775
776
This sends to the remote address specified in I<raddr> via the socket
777
I<buflen> bytes from buffer I<buf>. The actual number of sent bytes is
778
stored in I<bufdone>. This internally maps to sendto(2).
779
780
Example: C<sa_send(sa, buf, strlen(buf), NULL, saa);>
781
782
=item C<sa_rc_t >B<sa_sendf>C<(sa_t *>I<sa>C<, sa_addr_t *>I<raddr>C<, const char *>I<fmt>C<, ...);>
783
784
Send formatted data data to remote address via socket.
785
786
This formats a string according to the printf(3)-style format
787
specification I<fmt> and sends the result to the socket as a single
788
piece of data chunk. In case of a partial socket write, the not written
789
data of the formatted string is internally discarded.
790
791
The underlying string formatting engine is just a minimal one and for
792
security and independence reasons intentionally not directly based on
793
s[n]printf(3). It understands only the following format specifications:
794
"C<%%>", "C<%c>" (C<char>), "C<%s>" (C<char *>) and "C<%d>" (C<int>)
795
without any precision and padding possibilities. It is intended for
796
minimal formatting only. If you need more sophisticated formatting, you
797
have to format first into an own buffer via s[n]printf(3) and then send
798
this to the remote address via sa_send(3) instead.
799
800
Example: C<sa_sendf(sa, saa, "%s=%d\n", cp, i);>
801
802
=back
803
804
=head2 Socket Error Handling
805
806
This API part provides error handling operations only.
807
808
=over 4
809
810
=item C<char *>B<sa_error>C<(sa_rc_t >I<rv>C<);>
811
812
Return the string representation corresponding to the return code
813
value I<rv>. The returned string has to be treated read-only by the
814
application and is not required to be deallocated.
815
816
=back
817
818
=head1 SEE ALSO
819
820
=head2 Standards
821
822
R. Gilligan, S. Thomson, J. Bound, W. Stevens:
823
I<"Basic Socket Interface Extensions for IPv6">,
824
B<RFC 2553>, March 1999.
825
826
W. Stevens:
827
I<"Advanced Sockets API for IPv6">,
828
B<RFC 2292>, February 1998.
829
830
R. Fielding, L. Masinter, T. Berners-Lee:
831
I<"Uniform Resource Identifiers: Generic Syntax">,
832
B<RFC 2396>, August 1998.
833
834
R. Hinden, S. Deering:
835
I<"IP Version 6 Addressing Architecture">,
836
B<RFC 2373>, July 1998.
837
838
R. Hinden, B. Carpenter, L. Masinter:
839
I<"Format for Literal IPv6 Addresses in URL's">,
840
B<RFC 2732>, December 1999.
841
842
=head2 Papers
843
844
Stuart Sechrest:
845
I<"An Introductory 4.4BSD Interprocess Communication Tutorial">,
846
FreeBSD 4.4 (/usr/share/doc/psd/20.ipctut/).
847
848
Samuel J. Leffler, Robert S. Fabry, William N. Joy, Phil Lapsley:
849
I<"An Advanced 4.4BSD Interprocess Communication Tutorial">,
850
FreeBSD 4.4 (/usr/share/doc/psd/21.ipc/).
851
852
Craig Metz:
853
I<"Protocol Independence Using the Sockets API">,
854
http://www.usenix.org/publications/library/proceedings/usenix2000/freenix/metzprotocol.html,
855
USENIX Annual Technical Conference, June 2000.
856
857
=head2 Manual Pages
858
859
socket(2),
860
accept(2),
861
bind(2),
862
connect(2),
863
getpeername(2),
864
getsockname(2),
865
getsockopt(2),
866
ioctl(2),
867
listen(2),
868
read(2),
869
recv(2),
870
select(2),
871
send(2),
872
shutdown(2),
873
socketpair(2),
874
write(2),
875
getprotoent(3),
876
protocols(4).
877
878
=head1 HISTORY
879
880
B<OSSP sa> was invented in August 2001 by Ralf S. Engelschall
881
E<lt>rse@engelschall.comE<gt> under contract with Cable & Wireless
882
Germany E<lt>http://www.cw.com/deE<gt> for use inside the OSSP project.
883
Its creation was prompted by the requirement to implement an SMTP
884
logging channel for B<OSSP l2> (logging library). Its initial code was
885
derived from a predecessor sub-library originally written for socket
886
address abstraction inside B<OSSP lmtp2nntp>.
887
888
=head1 AUTHOR
889
890
Ralf S. Engelschall
891
rse@engelschall.com
892
www.engelschall.com
893
894
=cut
895
Loggerhead is a web-based interface for Breezy
Version: 2.0.1