userapps/opensource/net-snmp/man/snmp_sess_api.3.def

   1 .\" /***********************************************************
   2 .\"     Copyright 1989 by Carnegie Mellon University
   3 .\"
   4 .\"                       All Rights Reserved
   5 .\"
   6 .\" Permission to use, copy, modify, and distribute this software and its
   7 .\" documentation for any purpose and without fee is hereby granted,
   8 .\" provided that the above copyright notice appear in all copies and that
   9 .\" both that copyright notice and this permission notice appear in
  10 .\" supporting documentation, and that the name of CMU not be
  11 .\" used in advertising or publicity pertaining to distribution of the
  12 .\" software without specific, written prior permission.
  13 .\"
  14 .\" CMU DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
  15 .\" ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL
  16 .\" CMU BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR
  17 .\" ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
  18 .\" WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
  19 .\" ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
  20 .\" SOFTWARE.
  21 .\" ******************************************************************/
  22 .TH SNMP_SESS_API 3 "07 Mar 2002" VVERSIONINFO "Net-SNMP"
  23 .UC 5
  24 .SH NAME
  25 snmp_sess_init, snmp_sess_open, snmp_sess_session,
  26 snmp_sess_send, snmp_sess_async_send,
  27 snmp_sess_select_info, snmp_sess_read,
  28 snmp_sess_timeout, snmp_sess_close, snmp_sess_error - session functions
  29 .SH SYNOPSIS
  30 .B #include <net-snmp/session_api.h>
  31 .PP
  32 .BI "void snmp_sess_init(struct snmp_session *" session ");"
  33 .PP
  34 .BI "void *snmp_sess_open(struct snmp_session *" session ");"
  35 .PP
  36 .BI "struct snmp_session *snmp_sess_session(void *" handle ");"
  37 .PP
  38 .BI "int snmp_sess_send(void *" handle ", struct snmp_pdu *" pdu ");"
  39 .PP
  40 .BI "int snmp_sess_async_send(void *" handle ","
  41 .br
  42 .BI "                         struct snmp_pdu *" pdu ", "
  43 .br
  44 .BI "                         snmp_callback " callback ", "
  45 .br
  46 .BI "                         void *" callbackData ");"
  47 .PP
  48 .BI "int snmp_sess_select_info(void *" handle ","
  49 .br
  50 .BI "                          int *" numfds ", fd_set *" fdset ", "
  51 .br
  52 .BI "                          struct timeval *" timeout ", "
  53 .br
  54 .BI "                          int *" block ");"
  55 .PP
  56 .BI "void snmp_sess_read(void *" handle ", fd_set *" fdset ");"
  57 .PP
  58 .BI "void snmp_sess_timeout(void *" handle ");"
  59 .PP
  60 .BI "int snmp_sess_close(void *" handle ");"
  61 .PP
  62 .BI "void snmp_sess_error(void *" handle ", int *" pcliberr ", "
  63 .br
  64 .BI "                    int *" psnmperr ", char **" pperrstring ");"
  65 .SH DESCRIPTION
  66 These functions define a subset of the API that can be used
  67 to manage single SNMP sessions in a multi-threaded application.
  68 Except for
  69 .BR snmp_sess_session() ,
  70 these functions are single session versions of the traditional
  71 SNMP library API.
  72 .PP
  73 Note that these functions use an opaque pointer
  74 .RI ( handle
  75 in the above prototypes) to identify a single session in lieu of a
  76 .I session
  77 pointer (as in the traditional API).
  78 .PP
  79 .B snmp_sess_init()
  80 prepares a struct snmp_session that sources transport characteristics
  81 and common information that will be used for a set of SNMP transactions.
  82 After this structure is passed to
  83 .B snmp_sess_open()
  84 to create an SNMP session, the structure is no longer used.  Instead
  85 the opaque pointer returned by
  86 .B snmp_sess_open()
  87 is used to refer to that session henceforth.
  88 .PP
  89 SNMP sessions that are created with
  90 .B snmp_sess_open()
  91 are not affected by, and SHOULD NOT BE USED WITH,
  92 .BR snmp_select_info() ", " snmp_read() ", " snmp_timeout() " nor"
  93 .BR snmp_close() .
  94 Rather the equivalent single session functions described here should
  95 be used.
  96 .PP
  97 .B snmp_sess_init()
  98 and
  99 .B snmp_sess_open()
 100 each take as input a pointer to a struct snmp_session object.
 101 This structure contains information for a set of transactions that
 102 will share similar transport characteristics.
 103 .B snmp_sess_session()
 104 takes the opaque session handle and returns a pointer to
 105 its associated struct snmp_session.
 106 .PP
 107 .B snmp_sess_send()
 108 and
 109 .B snmp_sess_async_send()
 110 each take a
 111 .I pdu
 112 parameter, which points to a struct snmp_pdu object containing
 113 information that describes a transaction that will be performed over
 114 an open session.
 115 .PP
 116 Consult snmp_api.h for the definitions of these structures.
 117 .PP
 118 .BR snmp_sess_select_info() ", " snmp_sess_read() " and " snmp_sess_timeout()
 119 provide an interface for the use of the
 120 .BR select (2)
 121 system call so that SNMP transactions for a single session can occur
 122 asynchronously.
 123 .PP
 124 .B snmp_sess_select_info()
 125 is passed the information that would have been passed to
 126 .BR select (2)
 127 in the absence of SNMP.  For example, this might include file
 128 descriptors associated with the main loop of a graphical
 129 application. This information is modified so that SNMP will get the
 130 service it requires from the call to
 131 .BR select (2).
 132 In this case,
 133 .IR numfds ", " fdset " and " timeout
 134 correspond to the
 135 .IR nfds ", " readfds " and " timeout
 136 arguments to
 137 .BR select (2)
 138 respectively.  The only exception is that timeout must ALWAYS point to
 139 an allocated (but perhaps uninitialized)
 140 .I struct timeval
 141 (it cannot be NULL as for
 142 .BR select (2)).
 143 If
 144 .I timeout
 145 would have been passed as NULL,
 146 .I block
 147 is instead set to true, and
 148 .I timeout
 149 is treated as undefined.  This same rule applies upon return from
 150 .BR snmp_select_info() .
 151 .PP
 152 After calling
 153 .B snmp_sess_select_info() ,
 154 .BR select (2)
 155 should be called with the returned data.  When it returns,
 156 .B snmp_sess_read()
 157 should then be called with the
 158 .I fd_set
 159 returned from
 160 .BR select (2).
 161 This will read any input from this session's SNMP socket.  If
 162 .BR select (2)
 163 times out (that is, it returns zero),
 164 .B snmp_sess_timeout()
 165 should be called to see if a timeout has occurred on the SNMP
 166 session.
 167 .SH DIAGNOSTICS
 168 .PP
 169 Error return status from
 170 .B snmp_sess_open()
 171 is indicated by return of a NULL pointer.
 172 Error return status from
 173 .B snmp_sess_close()
 174 and
 175 .B snmp_sess_send()
 176 is indicated by a return value of 0.  A successful status will return
 177 1.
 178 .PP
 179 Further information can be obtained by using
 180 .B snmp_sess_error()
 181 to see what type of error has occurred.  This function returns the
 182 SNMP
 183 .I snmp_errno
 184 variable, the value of the system
 185 .I errno
 186 variable, and a string interpretation of both variables.  The string
 187 must be freed after use by the caller.
 188 .PP
 189 For errors returned by
 190 .BR snmp_sess_open() ,
 191 use the corresponding function
 192 .B snmp_error()
 193 instead of
 194 .BR snmp_sess_error() .
 195 .PP
 196 Consult snmp_api.h for the complete set of SNMP library
 197 error values.
 198 The SNMP library error value
 199 .IR snmperr
 200 can be one of the following values:
 201 .RS 2n
 202 .IP SNMPERR_GENERR \w'SNMPERR_BAD_REPETITIONS'u+2n
 203 A generic error occurred.
 204 .IP SNMPERR_BAD_LOCPORT \w'SNMPERR_BAD_REPETITIONS'u+2n
 205 The local port was bad because it had already been
 206 allocated or permission was denied.
 207 .IP SNMPERR_BAD_ADDRESS \w'SNMPERR_BAD_REPETITIONS'u+2n
 208 The host name or address given was not useable.
 209 .IP SNMPERR_BAD_SESSION \w'SNMPERR_BAD_REPETITIONS'u+2n
 210 The specified session was not open.
 211 .IP SNMPERR_TOO_LONG \w'SNMPERR_BAD_REPETITIONS'u+2n
 212 .IP SNMPERR_NO_SOCKET \w'SNMPERR_BAD_REPETITIONS'u+2n
 213 .IP SNMPERR_V2_IN_V1 \w'SNMPERR_BAD_REPETITIONS'u+2n
 214 .IP SNMPERR_V1_IN_V2 \w'SNMPERR_BAD_REPETITIONS'u+2n
 215 .IP SNMPERR_BAD_REPEATERS \w'SNMPERR_BAD_REPETITIONS'u+2n
 216 .IP SNMPERR_BAD_REPETITIONS \w'SNMPERR_BAD_REPETITIONS'u+2n
 217 .IP SNMPERR_BAD_ASN1_BUILD \w'SNMPERR_BAD_REPETITIONS'u+2n
 218 .IP SNMPERR_BAD_SENDTO \w'SNMPERR_BAD_REPETITIONS'u+2n
 219 .IP SNMPERR_BAD_RCVFROM \w'SNMPERR_BAD_REPETITIONS'u+2n
 220 .IP SNMPERR_BAD_PARSE \w'SNMPERR_BAD_REPETITIONS'u+2n
 221 .IP SNMPERR_BAD_VERSION \w'SNMPERR_BAD_REPETITIONS'u+2n
 222 .IP SNMPERR_BAD_COMMUNITY \w'SNMPERR_BAD_REPETITIONS'u+2n
 223 .IP SNMPERR_NOAUTH_DESPRIV \w'SNMPERR_BAD_REPETITIONS'u+2n
 224 .IP SNMPERR_ABORT \w'SNMPERR_BAD_REPETITIONS'u+2n
 225 .IP SNMPERR_UNKNOWN_PDU \w'SNMPERR_BAD_REPETITIONS'u+2n
 226 .IP SNMPERR_TIMEOUT \w'SNMPERR_BAD_REPETITIONS'u+2n
 227 .RE
 228 .PP
 229 .SH "SEE ALSO"
 230 .BR select "(2), " snmp_api "(3), " snmp_api.h