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