1 .\" /***********************************************************
2 .\" Copyright 1989 by Carnegie Mellon University
4 .\" All Rights Reserved
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.
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
21 .\" ******************************************************************/
22 .TH SNMP_API 3 "21 Oct 1999" VVERSIONINFO "Net-SNMP"
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
27 #include <net-snmp/session_api.h>
29 void snmp_sess_init ( struct snmp_session * );
31 struct snmp_session * snmp_open ( struct snmp_session *);
33 .B /* Input parameter not used in active sessions */
36 int snmp_send ( struct snmp_session *session,
38 struct snmp_pdu *pdu );
41 int snmp_select_info ( int *numfds, fd_set *fdset,
43 struct timeval *timeout, int *block );
46 void snmp_read ( fd_set *fdset );
48 void snmp_timeout ( void );
50 int snmp_close ( struct snmp_session *session );
53 struct snmp_pdu *pdu );
56 struct snmp_session *session,
63 char *snmp_api_errstring ( int snmperr );
65 void snmp_perror ( char * msg );
67 .B /* for parsing errors only */
70 void snmp_sess_perror (char * msg, struct snmp_session *);
72 .B /* all other SNMP library errors */
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
81 to create an SNMP session, the structure is not used.
84 returns a pointer to a newly-formed
85 .I struct snmp_session
86 object, which the application must use to reference the
92 each take as input a pointer to a
95 This structure contains information that describes a transaction
96 that will be performed over an open session.
98 Consult snmp_api.h for the definitions of these structures.
100 .I Snmp_read, snmp_select_info,
103 provide an interface for the use of the
105 system call so that SNMP transactions can occur asynchronously.
108 is given the information that would have been passed to
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
124 respectively. The only exception is that timeout must always point to an allocated (but perhaps uninitialized)
128 would have been passed as NULL,
132 is treated as undefined. This same rule applies upon return from
136 .I snmp_select_info, select
137 is called with the returned data. When select returns,
139 should be called with the
143 to read each SNMP socket that has input.
148 should be called to see if the timeout was intended for SNMP.
151 Previous versions of the library used
153 to read the global variable
155 which may have held the error status within the SNMP library.
158 should be used to log ASN.1 coding errors only.
162 is provided to capture errors that occur during the processing
163 of a particular SNMP session.
167 function to obtain the "C" library error
169 , the SNMP library error
171 , and the SNMP library detailed error message
172 that is associated with an error that occurred during a given session.
174 Note that in all cases except one,
177 .I struct snmp_session *
178 pointer returned from
182 returns a null pointer, pass the INPUT
183 .I struct snmp_session *
187 Error return status from
191 is indicated by return of 0. A successful status will return a 1 for
193 and then request id of the packet for
195 Upon successful return from
197 the pdu will be freed by the library.
199 Consult snmp_api.h for the complete set of SNMP library
201 The SNMP library error value
203 can be one of the following values:
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
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
234 that functions like the
238 select(2), snmp_api.h