external/bsd/openldap/man/lber-sockbuf.3

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