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