1 .TH LBER_SOCKBUF 3 "RELEASEDATE" "OpenLDAP LDVERSION"
3 .\" Copyright 1998-2007 The OpenLDAP Foundation All Rights Reserved.
4 .\" Copying restrictions apply. See COPYRIGHT/LICENSE.
6 ber_sockbuf_alloc, ber_sockbuf_free, ber_sockbuf_ctrl, ber_sockbuf_add_io,
7 ber_sockbuf_remove_io, Sockbuf_IO \- LBER I/O infrastructure
9 OpenLDAP LBER (liblber, -llber)
13 .B Sockbuf *ber_sockbuf_alloc( void );
15 .BI "void ber_sockbuf_free(Sockbuf *" sb ");"
17 .BI "int ber_sockbuf_ctrl(Sockbuf *" sb ", int " opt ", void *" arg ");"
19 .BI "int ber_sockbuf_add_io(Sockbuf *" sb ", Sockbuf_IO *" sbio ", int " layer ", void *" arg ");"
21 .BI "int ber_sockbuf_remove_io(Sockbuf *" sb ", Sockbuf_IO *" sbio ", int " layer ");"
24 .B typedef struct sockbuf_io_desc {
25 .BI "int " sbiod_level ";"
26 .BI "Sockbuf *" sbiod_sb ";"
27 .BI "Sockbuf_IO *" sbiod_io ";"
28 .BI "void *" sbiod_pvt ";"
29 .BI "struct sockbuf_io_desc *" sbiod_next ";"
32 .B typedef struct sockbuf_io {
33 .BI "int (*" sbi_setup ")(Sockbuf_IO_Desc *" sbiod ", void *" arg ");"
34 .BI "int (*" sbi_remove ")(Sockbuf_IO_Desc *" sbiod ");"
35 .BI "int (*" sbi_ctrl ")(Sockbuf_IO_Desc *" sbiod ", int " opt ", void *" arg ");"
36 .BI "ber_slen_t (*" sbi_read ")(Sockbuf_IO_Desc *" sbiod ", void *" buf ", ber_len_t " len ");"
37 .BI "ber_slen_t (*" sbi_write ")(Sockbuf_IO_Desc *" sbiod ", void *" buf ", ber_len_t " len ");"
38 .BI "int (*" sbi_close ")(Sockbuf_IO_Desc *" sbiod ");"
43 These routines are used to manage the low level I/O operations performed
44 by the Lightweight BER library. They are called implicitly by the other
45 libraries and usually do not need to be called directly from applications.
46 The I/O framework is modularized and new transport layers can be supported
47 by appropriately defining a
49 structure and installing it onto an existing
52 structures are allocated and freed by
53 .BR ber_sockbuf_alloc ()
55 .BR ber_sockbuf_free (),
57 .BR ber_sockbuf_ctrl ()
58 function is used to get and set options related to a
60 or to a specific I/O layer of the
63 .BR ber_sockbuf_add_io ()
65 .BR ber_sockbuf_remove_io ()
66 functions are used to add and remove specific I/O layers on a
70 .BR ber_sockbuf_ctrl ()
76 argument and returns 1 if the given handler is installed
82 Retrieves the file descriptor associated to the
86 .BR "ber_socket_t *" .
87 The return value will be 1 if a valid descriptor was present, -1 otherwise.
90 Sets the file descriptor of the
92 to the descriptor pointed to by
96 .BR "ber_socket_t *" .
97 The return value will always be 1.
99 .B LBER_SB_OPT_SET_NONBLOCK
100 Toggles the non-blocking state of the file descriptor associated to
104 should be NULL to disable and non-NULL to enable the non-blocking state.
105 The return value will be 1 for success, -1 otherwise.
108 Flush (read and discard) all available input on the
110 The return value will be 1.
112 .B LBER_SB_OPT_NEEDS_READ
113 Returns non-zero if input is waiting to be read.
115 .B LBER_SB_OPT_NEEDS_WRITE
116 Returns non-zero if the
118 is ready to be written.
120 .B LBER_SB_OPT_GET_MAX_INCOMING
121 Returns the maximum allowed size of an incoming message;
125 The return value will be 1.
127 .B LBER_SB_OPT_SET_MAX_INCOMING
128 Sets the maximum allowed size of an incoming message;
132 The return value will be 1.
135 Options not in this list will be passed down to each
137 handler in turn until one of them processes it. If the option is not handled
138 .BR ber_sockbuf_ctrl ()
144 handlers can be stacked in multiple layers to provide various functionality.
145 Currently defined layers include
147 .B LBER_SBIOD_LEVEL_PROVIDER
148 the lowest layer, talking directly to a network
150 .B LBER_SBIOD_LEVEL_TRANSPORT
151 an intermediate layer
153 .B LBER_SBIOD_LEVEL_APPLICATION
158 handlers in liblber include
160 .B ber_sockbuf_io_tcp
161 The default stream-oriented provider
163 .B ber_sockbuf_io_dgram
164 A datagram-oriented provider. This handler is only present if the liblber
165 library was built with LDAP_CONNECTIONLESS defined.
167 .B ber_sockbuf_io_readahead
168 A buffering layer, usually used with a datagram provider to hide the
169 datagram semantics from upper layers.
171 .B ber_sockbuf_io_debug
172 A generic handler that outputs hex dumps of all traffic.
174 Additional handlers may be present in libldap if support for them was
177 .B ldap_pvt_sockbuf_io_sasl
178 An application layer handler for SASL encoding/decoding.
181 A transport layer handler for SSL/TLS encoding/decoding. Note that this
182 handler is private to the library and is not exposed in the API.
184 The provided handlers are all instantiated implicitly by libldap, and
185 applications generally will not need to directly manipulate them.
191 .BR ldap_get_option (3)