git.sur5r.net Git - openldap/blob - doc/man/man3/lber-sockbuf.3

   1 .TH LBER_SOCKBUF 3 "RELEASEDATE" "OpenLDAP LDVERSION"
   2 .\" $OpenLDAP$
   3 .\" Copyright 1998-2007 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,
   7 ber_sockbuf_remove_io, Sockbuf_IO \- LBER I/O infrastructure
   8 .SH LIBRARY
   9 OpenLDAP 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
  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
  48 .B Sockbuf_IO
  49 structure and installing it onto an existing
  50 .BR Sockbuf .
  51 .B Sockbuf
  52 structures are allocated and freed by
  53 .BR ber_sockbuf_alloc ()
  54 and
  55 .BR ber_sockbuf_free (),
  56 respectively. The
  57 .BR ber_sockbuf_ctrl ()
  58 function is used to get and set options related to a
  59 .B Sockbuf
  60 or to a specific I/O layer of the
  61 .BR Sockbuf .
  62 The
  63 .BR ber_sockbuf_add_io ()
  64 and
  65 .BR ber_sockbuf_remove_io ()
  66 functions are used to add and remove specific I/O layers on a
  67 .BR Sockbuf .
  68
  69 Options for
  70 .BR ber_sockbuf_ctrl ()
  71 include:
  72 .TP
  73 .B LBER_SB_OPT_HAS_IO
  74 Takes a
  75 .B Sockbuf_IO *
  76 argument and returns 1 if the given handler is installed
  77 on the
  78 .BR Sockbuf ,
  79 otherwise returns 0.
  80 .TP
  81 .B LBER_SB_OPT_GET_FD
  82 Retrieves the file descriptor associated to the
  83 .BR Sockbuf ;
  84 .B arg
  85 must be a
  86 .BR "ber_socket_t *" .
  87 The return value will be 1 if a valid descriptor was present, -1 otherwise.
  88 .TP
  89 .B LBER_SB_OPT_SET_FD
  90 Sets the file descriptor of the
  91 .B Sockbuf
  92 to the descriptor pointed to by
  93 .BR arg ;
  94 .B arg
  95 must be a
  96 .BR "ber_socket_t *" .
  97 The return value will always be 1.
  98 .TP
  99 .B LBER_SB_OPT_SET_NONBLOCK
 100 Toggles the non-blocking state of the file descriptor associated to
 101 the
 102 .BR Sockbuf .
 103 .B arg
 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.
 106 .TP
 107 .B LBER_SB_OPT_DRAIN
 108 Flush (read and discard) all available input on the
 109 .BR Sockbuf .
 110 The return value will be 1.
 111 .TP
 112 .B LBER_SB_OPT_NEEDS_READ
 113 Returns non-zero if input is waiting to be read.
 114 .TP
 115 .B LBER_SB_OPT_NEEDS_WRITE
 116 Returns non-zero if the
 117 .B Sockbuf
 118 is ready to be written.
 119 .TP
 120 .B LBER_SB_OPT_GET_MAX_INCOMING
 121 Returns the maximum allowed size of an incoming message;
 122 .B arg
 123 must be a
 124 .BR "ber_len_t *" .
 125 The return value will be 1.
 126 .TP
 127 .B LBER_SB_OPT_SET_MAX_INCOMING
 128 Sets the maximum allowed size of an incoming message;
 129 .B arg
 130 must be a
 131 .BR "ber_len_t *" .
 132 The return value will be 1.
 133
 134 .LP
 135 Options not in this list will be passed down to each
 136 .B Sockbuf_IO
 137 handler in turn until one of them processes it. If the option is not handled
 138 .BR ber_sockbuf_ctrl ()
 139 will return 0.
 140
 141 .LP
 142 Multiple
 143 .B Sockbuf_IO
 144 handlers can be stacked in multiple layers to provide various functionality.
 145 Currently defined layers include
 146 .TP
 147 .B LBER_SBIOD_LEVEL_PROVIDER
 148 the lowest layer, talking directly to a network
 149 .TP
 150 .B LBER_SBIOD_LEVEL_TRANSPORT
 151 an intermediate layer
 152 .TP
 153 .B LBER_SBIOD_LEVEL_APPLICATION
 154 a higher layer
 155 .LP
 156 Currently defined
 157 .B Sockbuf_IO
 158 handlers in liblber include
 159 .TP
 160 .B ber_sockbuf_io_tcp
 161 The default stream-oriented provider
 162 .TP
 163 .B ber_sockbuf_io_fd
 164 A stream-oriented provider for local IPC sockets
 165 .TP
 166 .B ber_sockbuf_io_dgram
 167 A datagram-oriented provider. This handler is only present if the liblber
 168 library was built with LDAP_CONNECTIONLESS defined.
 169 .TP
 170 .B ber_sockbuf_io_readahead
 171 A buffering layer, usually used with a datagram provider to hide the
 172 datagram semantics from upper layers.
 173 .TP
 174 .B ber_sockbuf_io_debug
 175 A generic handler that outputs hex dumps of all traffic. This handler
 176 may be inserted multiple times at arbitrary layers to show the flow
 177 of data between other handlers.
 178 .LP
 179 Additional handlers may be present in libldap if support for them was
 180 enabled:
 181 .TP
 182 .B ldap_pvt_sockbuf_io_sasl
 183 An application layer handler for SASL encoding/decoding.
 184 .TP
 185 .B sb_tls_sbio
 186 A transport layer handler for SSL/TLS encoding/decoding. Note that this
 187 handler is private to the library and is not exposed in the API.
 188 .LP
 189 The provided handlers are all instantiated implicitly by libldap, and
 190 applications 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 .so ../Project