1NETSNMP_SESSION_API(3)             Net-SNMP             NETSNMP_SESSION_API(3)
2
3
4

NAME

6       snmp_sess_init,       snmp_open,       snmp_send,      snmp_async_send,
7       snmp_select_info,   snmp_read,    snmp_timeout,    snmp_synch_response,
8       snmp_close,       snmp_perror,       snmp_sess_perror,      snmp_error,
9       snmp_api_errstring - netsnmp_session_api functions
10

SYNOPSIS

12       #include <net-snmp/session_api.h>
13
14       void snmp_sess_init ( netsnmp_session*sess);
15
16       netsnmp_session* snmp_open ( netsnmp_session *sess);
17              /* Input parameter not used in active sessions */
18
19       int snmp_send ( netsnmp_session *session,
20              netsnmp_pdu *pdu);
21
22       int snmp_async_send ( netsnmp_session *session,
23                                       netsnmp_pdu *pdu,
24                                       snmp_callback callback,
25                                       void *callbackData);
26
27       int snmp_select_info ( int * numfds,fd_set *fdset,
28              struct timeval *timeout,int *block);
29
30       void snmp_read ( fd_set *fdset);
31
32       void snmp_timeout ( void );
33
34       int snmp_synch_response ( netsnmp_session *session,
35              netsnmp_pdu *pdu,
36              netsnmp_pdu **response);
37
38       int snmp_close ( netsnmp_session *session);
39       int snmp_close_sessions ( void );
40
41   Error Reporting
42       (Move to output_api(3))
43       void snmp_error ( netsnmp_session *session,
44              int *pcliberr,int *psnmperr,char **pperrstring);
45
46       char *snmp_api_errstring ( intsnmperr);
47
48       void snmp_perror ( char *msg);
49              /* for parsing errors only */
50
51       void snmp_sess_perror (char *msg,netsnmp_session *sess);
52              /* all other SNMP library errors */
53

DESCRIPTION

55       Snmp_sess_init prepares a netsnmp_session that sources transport  char‐
56       acteristics  and common information that will be used for a set of SNMP
57       transactions.  After this structure is passed to snmp_open to create an
58       SNMP session, the structure is not used.
59
60       Snmp_open  returns  a pointer to a newly-formed netsnmp_session object,
61       which the application must use to reference the active SNMP session.
62
63       snmp_send and snmp_async_send() each take as input a pointer to a  net‐
64       snmp_pdu  object.  This structure contains information that describes a
65       transaction that will be performed over an open session.
66
67       Consult snmp_api.h for the definitions of these structures.
68
69       With the snmp_async_send() call, snmp_read will  invoke  the  specified
70       callback when the response is received.
71
72       Snmp_read,  snmp_select_info, and snmp_timeout provide an interface for
73       the use of the select(2) system call  so  that  SNMP  transactions  can
74       occur asynchronously.
75
76       Snmp_select_info  is  given the information that would have been passed
77       to select in the absence of SNMP.  For example, this might include win‐
78       dow update information.  This information is modified so that SNMP will
79       get the service it requires from the call to  select.   In  this  case,
80       numfds, fdset, and timeout correspond to the nfds, readfds, and timeout
81       arguments to select, respectively.  The only exception is that  timeout
82       must  always  point  to an allocated (but perhaps uninitialized) struct
83       timeval.  If timeout would have been passed as NULL, block  is  set  to
84       true, and timeout is treated as undefined.  This same rule applies upon
85       return from snmp_select_info.
86
87       After calling snmp_select_info, select  is  called  with  the  returned
88       data.   When select returns, snmp_read should be called with the fd_set
89       returned from select to read each  SNMP  socket  that  has  input.   If
90       select  times  out, snmp_timeout should be called to see if the timeout
91       was intended for SNMP.
92
93       snmp_synch_response  is  a  convenience  routine  that  will  send  the
94       request,  wait  for  the response and process it before returning.  See
95       the descriptions of snmp_send ,  snmp_read etc for details.
96

DIAGNOSTICS

98       Previous versions of the library used snmp_get_errno to read the global
99       variable  snmp_errno  which  may  have held the error status within the
100       SNMP library.  The existing method snmp_perror should be  used  to  log
101       ASN.1 coding errors only.
102
103       The  new  method  snmp_sess_perror  is  provided to capture errors that
104       occur  during  the   processing   of   a   particular   SNMP   session.
105       Snmp_sess_perror  calls  snmp_error  function to obtain the "C" library
106       error errno , the SNMP library error snmperr ,  and  the  SNMP  library
107       detailed  error  message that is associated with an error that occurred
108       during a given session.
109
110       Note that in all cases except one, snmp_sess_perror  should  be  handed
111       the  netsnmp_session  *  pointer returned from snmp_open.  If snmp_open
112       returns a null pointer, pass the INPUT netsnmp_session *  pointer  used
113       to call snmp_open.
114
115       Error  return  status  from  snmp_close  and  snmp_send is indicated by
116       return of 0.  A successful status will return a 1  for  snmp_close  and
117       the  request  id  of  the packet for snmp_send.  Upon successful return
118       from snmp_send the pdu will be freed by the library.
119
120       Consult snmp_api.h for the complete set of SNMP library  error  values.
121       The  SNMP  library error value snmperr can be one of the following val‐
122       ues:
123
124         SNMPERR_GENERR           A generic error occurred.
125
126         SNMPERR_BAD_LOCPORT      The  local  port  was  bad  because  it  had
127                                  already  been  allocated  or  permission was
128                                  denied.
129
130         SNMPERR_BAD_ADDRESS      The host name or address given was not  use‐
131                                  able.
132
133         SNMPERR_BAD_SESSION      The specified session was not open.
134
135         SNMPERR_TOO_LONG
136
137         SNMPERR_NO_SOCKET
138
139         SNMPERR_V2_IN_V1
140
141         SNMPERR_V1_IN_V2
142
143         SNMPERR_BAD_REPEATERS
144
145         SNMPERR_BAD_REPETITIONS
146
147         SNMPERR_BAD_ASN1_BUILD
148
149         SNMPERR_BAD_SENDTO
150
151         SNMPERR_BAD_PARSE
152
153         SNMPERR_BAD_VERSION
154
155         SNMPERR_NOAUTH_DESPRIV
156
157         SNMPERR_ABORT
158
159         SNMPERR_UNKNOWN_PDU
160
161         SNMPERR_TIMEOUT
162
163       A  string  representation  of  the  error  code  can  be  obtained with
164       snmp_api_errstring, and a standard error message may be  printed  using
165       snmp_perror that functions like the perror standard routine.
166

SEE ALSO

168       select(2), netsnmp_sess_api(3), netsnmp_mib_api(3), netsnmp_pdu_api(3),
169       netsnmp_varbind_api(3), snmp_api.h
170
171
172
173V5.8                              19 May 2011           NETSNMP_SESSION_API(3)
Impressum