1SNMP_API(3) Net-SNMP SNMP_API(3)
2
3
4
6 snmp_sess_init, snmp_open, snmp_send, snmp_free_pdu, snmp_select_info,
7 snmp_read, snmp_timeout, snmp_close, snmp_perror, snmp_sess_perror,
8 snmp_error, snmp_api_errstring - send and receive SNMP messages
9
11 #include <net-snmp/session_api.h>
12
13 void snmp_sess_init ( struct snmp_session * );
14
15 struct snmp_session * snmp_open ( struct snmp_session *);
16 /* Input parameter not used in active sessions */
17
18 int snmp_send ( struct snmp_session *session,
19 struct snmp_pdu *pdu );
20
21 int snmp_select_info ( int *numfds, fd_set *fdset,
22 struct timeval *timeout, int *block );
23
24 void snmp_read ( fd_set *fdset );
25
26 void snmp_timeout ( void );
27
28 int snmp_close ( struct snmp_session *session );
29
30 void snmp_free_pdu ( struct snmp_pdu *pdu );
31
32 void snmp_error ( struct snmp_session *session,
33 int *pcliberr, int *psnmperr, char **pperrstring );
34
35 char *snmp_api_errstring ( int snmperr );
36
37 void snmp_perror ( char * msg );
38 /* for parsing errors only */
39
40 void snmp_sess_perror (char * msg, struct snmp_session *);
41 /* all other SNMP library errors */
42
44 Snmp_sess_init prepares a struct snmp_session that sources transport
45 characteristics and common information that will be used for a set of
46 SNMP transactions. After this structure is passed to snmp_open to cre‐
47 ate an SNMP session, the structure is not used.
48
49 Snmp_open returns a pointer to a newly-formed struct snmp_session
50 object, which the application must use to reference the active SNMP
51 session.
52
53 Snmp_send and snmp_free_pdu each take as input a pointer to a struct
54 snmp_pdu object. This structure contains information that describes a
55 transaction that will be performed over an open session.
56
57 Consult snmp_api.h for the definitions of these structures.
58
59 Snmp_read, snmp_select_info, and snmp_timeout provide an interface for
60 the use of the select(2) system call so that SNMP transactions can
61 occur asynchronously.
62
63 Snmp_select_info is given the information that would have been passed
64 to select in the absence of SNMP. For example, this might include win‐
65 dow update information. This information is modified so that SNMP will
66 get the service it requires from the call to select. In this case,
67 numfds, fdset, and timeout correspond to the nfds, readfds, and timeout
68 arguments to select, respectively. The only exception is that timeout
69 must always point to an allocated (but perhaps uninitialized) struct
70 timeval. If timeout would have been passed as NULL, block is set to
71 true, and timeout is treated as undefined. This same rule applies upon
72 return from snmp_select_info.
73
74 After calling snmp_select_info, select is called with the returned
75 data. When select returns, snmp_read should be called with the fd_set
76 returned from select to read each SNMP socket that has input. If
77 select times out, snmp_timeout should be called to see if the timeout
78 was intended for SNMP.
79
81 Previous versions of the library used snmp_get_errno to read the global
82 variable snmp_errno which may have held the error status within the
83 SNMP library. The existing method snmp_perror should be used to log
84 ASN.1 coding errors only.
85
86 The new method snmp_sess_perror is provided to capture errors that
87 occur during the processing of a particular SNMP session.
88 Snmp_sess_perror calls snmp_error function to obtain the "C" library
89 error errno , the SNMP library error snmperr , and the SNMP library
90 detailed error message that is associated with an error that occurred
91 during a given session.
92
93 Note that in all cases except one, snmp_sess_perror should be handed
94 the struct snmp_session * pointer returned from snmp_open. If
95 snmp_open returns a null pointer, pass the INPUT struct snmp_session *
96 pointer used to call snmp_open.
97
98 Error return status from snmp_close and snmp_send is indicated by
99 return of 0. A successful status will return a 1 for snmp_close and
100 the request id of the packet for snmp_send. Upon successful return
101 from snmp_send the pdu will be freed by the library.
102
103 Consult snmp_api.h for the complete set of SNMP library error values.
104 The SNMP library error value snmperr can be one of the following val‐
105 ues:
106
107 SNMPERR_GENERR A generic error occurred.
108
109 SNMPERR_BAD_LOCPORT The local port was bad because it had
110 already been allocated or permission was
111 denied.
112
113 SNMPERR_BAD_ADDRESS The host name or address given was not use‐
114 able.
115
116 SNMPERR_BAD_SESSION The specified session was not open.
117
118 SNMPERR_TOO_LONG
119
120 SNMPERR_NO_SOCKET
121
122 SNMPERR_V2_IN_V1
123
124 SNMPERR_V1_IN_V2
125
126 SNMPERR_BAD_REPEATERS
127
128 SNMPERR_BAD_REPETITIONS
129
130 SNMPERR_BAD_ASN1_BUILD
131
132 SNMPERR_BAD_SENDTO
133
134 SNMPERR_BAD_PARSE
135
136 SNMPERR_BAD_VERSION
137
138 SNMPERR_NOAUTH_DESPRIV
139
140 SNMPERR_ABORT
141
142 SNMPERR_UNKNOWN_PDU
143
144 SNMPERR_TIMEOUT
145
146 A string representation of the error code can be obtained with
147 snmp_api_errstring, and a standard error message may be printed using
148 snmp_perror that functions like the perror standard routine.
149
151 select(2), snmp_api.h
152
153
154
1554.2 Berkeley Distribution 21 Oct 1999 SNMP_API(3)