1.lf 1 stdin
2.TH LBER_SOCKBUF 3 "2020/04/28" "OpenLDAP 2.4.50"
3.\" $OpenLDAP$
4.\" Copyright 1998-2020 The OpenLDAP Foundation All Rights Reserved.
5.\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
6.SH NAME
7ber_sockbuf_alloc, ber_sockbuf_free, ber_sockbuf_ctrl, ber_sockbuf_add_io, ber_sockbuf_remove_io, Sockbuf_IO \- OpenLDAP LBER I/O infrastructure
8.SH LIBRARY
9OpenLDAP LBER (liblber, \-llber)
10.SH SYNOPSIS
11.B #include <lber.h>
12.LP
13.B Sockbuf *ber_sockbuf_alloc( void );
14.LP
15.BI "void ber_sockbuf_free(Sockbuf *" sb ");"
16.LP
17.BI "int ber_sockbuf_ctrl(Sockbuf *" sb ", int " opt ", void *" arg ");"
18.LP
19.BI "int ber_sockbuf_add_io(Sockbuf *" sb ", Sockbuf_IO *" sbio ", int " layer ", void *" arg ");"
20.LP
21.BI "int ber_sockbuf_remove_io(Sockbuf *" sb ", Sockbuf_IO *" sbio ", int " layer ");"
22.LP
23.nf
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 ";"
30.B } Sockbuf_IO_Desc;
31.LP
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 ");"
39.B } Sockbuf_IO;
40
41.SH DESCRIPTION
42.LP
43These routines are used to manage the low level I/O operations performed
44by the Lightweight BER library. They are called implicitly by the other
45libraries and usually do not need to be called directly from applications.
46The I/O framework is modularized and new transport layers can be supported
47by appropriately defining a
48.B Sockbuf_IO
49structure and installing it onto an existing
50.BR Sockbuf .
51.B Sockbuf
52structures are allocated and freed by
53.BR ber_sockbuf_alloc ()
54and
55.BR ber_sockbuf_free (),
56respectively. The
57.BR ber_sockbuf_ctrl ()
58function is used to get and set options related to a
59.B Sockbuf
60or to a specific I/O layer of the
61.BR Sockbuf .
62The
63.BR ber_sockbuf_add_io ()
64and
65.BR ber_sockbuf_remove_io ()
66functions are used to add and remove specific I/O layers on a
67.BR Sockbuf .
68
69Options for
70.BR ber_sockbuf_ctrl ()
71include:
72.TP
73.B LBER_SB_OPT_HAS_IO
74Takes a
75.B Sockbuf_IO *
76argument and returns 1 if the given handler is installed
77on the
78.BR Sockbuf ,
79otherwise returns 0.
80.TP
81.B LBER_SB_OPT_GET_FD
82Retrieves the file descriptor associated to the
83.BR Sockbuf ;
84.B arg
85must be a
86.BR "ber_socket_t *" .
87The return value will be 1 if a valid descriptor was present, \-1 otherwise.
88.TP
89.B LBER_SB_OPT_SET_FD
90Sets the file descriptor of the
91.B Sockbuf
92to the descriptor pointed to by
93.BR arg ;
94.B arg
95must be a
96.BR "ber_socket_t *" .
97The return value will always be 1.
98.TP
99.B LBER_SB_OPT_SET_NONBLOCK
100Toggles the non-blocking state of the file descriptor associated to
101the
102.BR Sockbuf .
103.B arg
104should be NULL to disable and non-NULL to enable the non-blocking state.
105The return value will be 1 for success, \-1 otherwise.
106.TP
107.B LBER_SB_OPT_DRAIN
108Flush (read and discard) all available input on the
109.BR Sockbuf .
110The return value will be 1.
111.TP
112.B LBER_SB_OPT_NEEDS_READ
113Returns non-zero if input is waiting to be read.
114.TP
115.B LBER_SB_OPT_NEEDS_WRITE
116Returns non-zero if the
117.B Sockbuf
118is ready to be written.
119.TP
120.B LBER_SB_OPT_GET_MAX_INCOMING
121Returns the maximum allowed size of an incoming message;
122.B arg
123must be a
124.BR "ber_len_t *" .
125The return value will be 1.
126.TP
127.B LBER_SB_OPT_SET_MAX_INCOMING
128Sets the maximum allowed size of an incoming message;
129.B arg
130must be a
131.BR "ber_len_t *" .
132The return value will be 1.
133
134.LP
135Options not in this list will be passed down to each
136.B Sockbuf_IO
137handler in turn until one of them processes it. If the option is not handled
138.BR ber_sockbuf_ctrl ()
139will return 0.
140
141.LP
142Multiple
143.B Sockbuf_IO
144handlers can be stacked in multiple layers to provide various functionality.
145Currently defined layers include
146.TP
147.B LBER_SBIOD_LEVEL_PROVIDER
148the lowest layer, talking directly to a network 
149.TP
150.B LBER_SBIOD_LEVEL_TRANSPORT
151an intermediate layer
152.TP
153.B LBER_SBIOD_LEVEL_APPLICATION
154a higher layer
155.LP
156Currently defined
157.B Sockbuf_IO
158handlers in liblber include
159.TP
160.B ber_sockbuf_io_tcp
161The default stream-oriented provider
162.TP
163.B ber_sockbuf_io_fd
164A stream-oriented provider for local IPC sockets
165.TP
166.B ber_sockbuf_io_dgram
167A datagram-oriented provider. This handler is only present if the liblber
168library was built with LDAP_CONNECTIONLESS defined.
169.TP
170.B ber_sockbuf_io_readahead
171A buffering layer, usually used with a datagram provider to hide the
172datagram semantics from upper layers.
173.TP
174.B ber_sockbuf_io_debug
175A generic handler that outputs hex dumps of all traffic. This handler
176may be inserted multiple times at arbitrary layers to show the flow
177of data between other handlers.
178.LP
179Additional handlers may be present in libldap if support for them was
180enabled:
181.TP
182.B ldap_pvt_sockbuf_io_sasl
183An application layer handler for SASL encoding/decoding.
184.TP
185.B sb_tls_sbio
186A transport layer handler for SSL/TLS encoding/decoding. Note that this
187handler is private to the library and is not exposed in the API.
188.LP
189The provided handlers are all instantiated implicitly by libldap, and
190applications generally will not need to directly manipulate them.
191
192.SH SEE ALSO
193.BR lber-decode (3),
194.BR lber-encode (3),
195.BR lber-types (3),
196.BR ldap_get_option (3)
197
198.LP
199.SH ACKNOWLEDGEMENTS
200.lf 1 ./../Project
201.\" Shared Project Acknowledgement Text
202.B "OpenLDAP Software"
203is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>.
204.B "OpenLDAP Software"
205is derived from the University of Michigan LDAP 3.3 Release.  
206.lf 200 stdin
207