userapps/opensource/net-snmp/man/snmp_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_API 3 "21 Oct 1999" VVERSIONINFO "Net-SNMP"
  23 .UC 5
  24 .SH NAME
  25 snmp_sess_init, snmp_open, snmp_send, snmp_free_pdu, snmp_select_info, snmp_read, snmp_timeout, snmp_close, snmp_perror, snmp_sess_perror, snmp_error, snmp_api_errstring \- send and receive SNMP messages
  26 .SH SYNOPSIS
  27 #include <net-snmp/session_api.h>
  28 .PP
  29 void snmp_sess_init ( struct snmp_session * );
  30 .PP
  31 struct snmp_session * snmp_open ( struct snmp_session *);
  32 .RS
  33 .B /* Input parameter not used in active sessions */
  34 .RE
  35 .PP
  36 int snmp_send ( struct snmp_session *session,
  37 .RS
  38 struct snmp_pdu *pdu );
  39 .RE
  40 .PP
  41 int snmp_select_info ( int *numfds, fd_set *fdset,
  42 .RS
  43 struct timeval *timeout, int *block );
  44 .RE
  45 .PP
  46 void snmp_read ( fd_set *fdset );
  47 .PP
  48 void snmp_timeout ( void );
  49 .PP
  50 int snmp_close ( struct snmp_session *session );
  51 .PP
  52 void snmp_free_pdu (
  53 struct snmp_pdu *pdu );
  54 .PP
  55 void snmp_error (
  56 struct snmp_session *session,
  57 .RS
  58 int *pcliberr,
  59 int *psnmperr,
  60 char **pperrstring );
  61 .RE
  62 .PP
  63 char *snmp_api_errstring ( int snmperr );
  64 .PP
  65 void snmp_perror ( char * msg );
  66 .RS
  67 .B /* for parsing errors only */
  68 .RE
  69 .PP
  70 void snmp_sess_perror (char * msg, struct snmp_session *);
  71 .RS
  72 .B /* all other SNMP library errors */
  73 .RE
  74 .PP
  75 .SH DESCRIPTION
  76 .I Snmp_sess_init
  77 prepares a struct snmp_session that sources transport characteristics
  78 and common information that will be used for a set of SNMP transactions.
  79 After this structure is passed to
  80 .I snmp_open
  81 to create an SNMP session, the structure is not used.
  82 .PP
  83 .I Snmp_open
  84 returns a pointer to a newly-formed
  85 .I struct snmp_session
  86 object, which the application must use to reference the
  87 active SNMP session.
  88 .PP
  89 .I Snmp_send
  90 and
  91 .I snmp_free_pdu
  92 each take as input a pointer to a
  93 .I struct snmp_pdu
  94 object.
  95 This structure contains information that describes a transaction
  96 that will be performed over an open session.
  97 .PP
  98 Consult snmp_api.h for the definitions of these structures.
  99 .PP
 100 .I Snmp_read, snmp_select_info,
 101 and
 102 .I snmp_timeout
 103 provide an interface for the use of the
 104 .IR select(2)
 105 system call so that SNMP transactions can occur asynchronously.
 106 .PP
 107 .I Snmp_select_info
 108 is given the information that would have been passed to
 109 .I select
 110 in the absence of SNMP.  For example, this might include window update information.
 111 This information is modified so that SNMP will get the service it requires from the
 112 call to
 113 .I select.
 114 In this case,
 115 .I numfds, fdset,
 116 and
 117 .I timeout
 118 correspond to the
 119 .I nfds, readfds,
 120 and
 121 .I timeout
 122 arguments to
 123 .I select,
 124 respectively.  The only exception is that timeout must always point to an allocated (but perhaps uninitialized)
 125 .I struct timeval.
 126 If
 127 .I timeout
 128 would have been passed as NULL,
 129 .I block
 130 is set to true, and
 131 .I timeout
 132 is treated as undefined.  This same rule applies upon return from
 133 .I snmp_select_info.
 134 .PP
 135 After calling
 136 .I snmp_select_info, select
 137 is called with the returned data.  When select returns,
 138 .I snmp_read
 139 should be called with the
 140 .I fd_set
 141 returned from
 142 .I select
 143 to read each SNMP socket that has input.
 144 If
 145 .I select
 146 times out,
 147 .I snmp_timeout
 148 should be called to see if the timeout was intended for SNMP.
 149 .SH DIAGNOSTICS
 150 .PP
 151 Previous versions of the library used
 152 .IR snmp_get_errno
 153 to read the global variable
 154 .I snmp_errno
 155 which may have held the error status within the SNMP library.
 156 The existing method
 157 .I snmp_perror
 158 should be used to log ASN.1 coding errors only.
 159 .PP
 160 The new method
 161 .I snmp_sess_perror
 162 is provided to capture errors that occur during the processing
 163 of a particular SNMP session.
 164 .I Snmp_sess_perror
 165 calls
 166 .IR snmp_error
 167 function to obtain the "C" library error
 168 .I errno
 169 , the SNMP library error
 170 .I snmperr
 171 , and the SNMP library detailed error message
 172 that is associated with an error that occurred during a given session.
 173 .PP
 174 Note that in all cases except one,
 175 .IR snmp_sess_perror
 176 should be handed the
 177 .I struct snmp_session *
 178 pointer returned from
 179 .IR snmp_open.
 180 If
 181 .IR snmp_open
 182 returns a null pointer, pass the INPUT
 183 .I struct snmp_session *
 184 pointer used to call
 185 .IR snmp_open.
 186 .PP
 187 Error return status from
 188 .I snmp_close
 189 and
 190 .I snmp_send
 191 is indicated by return of 0.  A successful status will return a 1 for
 192 .I snmp_close
 193 and then request id of the packet for
 194 .I snmp_send.
 195 Upon successful return from
 196 .I snmp_send
 197 the pdu will be freed by the library.
 198 .PP
 199 Consult snmp_api.h for the complete set of SNMP library
 200 error values.
 201 The SNMP library error value
 202 .IR snmperr
 203 can be one of the following values:
 204 .RS 2n
 205 .IP SNMPERR_GENERR \w'SNMPERR_BAD_REPETITIONS'u+2n
 206 A generic error occurred.
 207 .IP SNMPERR_BAD_LOCPORT \w'SNMPERR_BAD_REPETITIONS'u+2n
 208 The local port was bad because it had already been
 209 allocated or permission was denied.
 210 .IP SNMPERR_BAD_ADDRESS \w'SNMPERR_BAD_REPETITIONS'u+2n
 211 The host name or address given was not useable.
 212 .IP SNMPERR_BAD_SESSION \w'SNMPERR_BAD_REPETITIONS'u+2n
 213 The specified session was not open.
 214 .IP SNMPERR_TOO_LONG \w'SNMPERR_BAD_REPETITIONS'u+2n
 215 .IP SNMPERR_NO_SOCKET \w'SNMPERR_BAD_REPETITIONS'u+2n
 216 .IP SNMPERR_V2_IN_V1 \w'SNMPERR_BAD_REPETITIONS'u+2n
 217 .IP SNMPERR_V1_IN_V2 \w'SNMPERR_BAD_REPETITIONS'u+2n
 218 .IP SNMPERR_BAD_REPEATERS \w'SNMPERR_BAD_REPETITIONS'u+2n
 219 .IP SNMPERR_BAD_REPETITIONS \w'SNMPERR_BAD_REPETITIONS'u+2n
 220 .IP SNMPERR_BAD_ASN1_BUILD \w'SNMPERR_BAD_REPETITIONS'u+2n
 221 .IP SNMPERR_BAD_SENDTO \w'SNMPERR_BAD_REPETITIONS'u+2n
 222 .IP SNMPERR_BAD_PARSE \w'SNMPERR_BAD_REPETITIONS'u+2n
 223 .IP SNMPERR_BAD_VERSION \w'SNMPERR_BAD_REPETITIONS'u+2n
 224 .IP SNMPERR_NOAUTH_DESPRIV \w'SNMPERR_BAD_REPETITIONS'u+2n
 225 .IP SNMPERR_ABORT \w'SNMPERR_BAD_REPETITIONS'u+2n
 226 .IP SNMPERR_UNKNOWN_PDU \w'SNMPERR_BAD_REPETITIONS'u+2n
 227 .IP SNMPERR_TIMEOUT \w'SNMPERR_BAD_REPETITIONS'u+2n
 228 .RE
 229 .PP
 230 A string representation of the error code can be obtained with
 231 .IR snmp_api_errstring ,
 232 and a standard error message may be printed using
 233 .I snmp_perror
 234 that functions like the
 235 .I perror
 236 standard routine.
 237 .SH "SEE ALSO"
 238 select(2), snmp_api.h