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

NAME

6       snmp_sess_init,   snmp_sess_open,   snmp_sess_session,  snmp_sess_send,
7       snmp_sess_async_send,      snmp_sess_select_info,       snmp_sess_read,
8       snmp_sess_timeout, snmp_sess_close, snmp_sess_error - session functions
9

SYNOPSIS

11       #include <net-snmp/session_api.h>
12
13       void snmp_sess_init(struct snmp_session *session);
14
15       void *snmp_sess_open(struct snmp_session *session);
16
17       struct snmp_session *snmp_sess_session(void *handle);
18
19       int snmp_sess_send(void *handle, struct snmp_pdu *pdu);
20
21       int snmp_sess_async_send(void *handle,
22                                struct snmp_pdu *pdu,
23                                snmp_callback callback,
24                                void *callbackData);
25
26       int snmp_sess_select_info(void *handle,
27                                 int *numfds, fd_set *fdset,
28                                 struct timeval *timeout,
29                                 int *block);
30
31       int snmp_sess_read(void *handle, fd_set *fdset);
32
33       void snmp_sess_timeout(void *handle);
34
35       int snmp_sess_close(void *handle);
36
37       void snmp_sess_error(void *handle, int *pcliberr,
38                           int *psnmperr, char **pperrstring);
39

DESCRIPTION

41       These  functions  define a subset of the API that can be used to manage
42       single SNMP sessions  in  a  multi-threaded  application.   Except  for
43       snmp_sess_session(), these functions are single session versions of the
44       traditional SNMP library API.
45
46       Note that these functions use an opaque pointer (handle  in  the  above
47       prototypes)  to  identify a single session in lieu of a session pointer
48       (as in the traditional API).
49
50       snmp_sess_init() prepares a struct snmp_session that sources  transport
51       characteristics  and  common information that will be used for a set of
52       SNMP transactions.  After this structure is passed to  snmp_sess_open()
53       to  create  an  SNMP session, the structure is no longer used.  Instead
54       the opaque pointer returned by snmp_sess_open() is  used  to  refer  to
55       that session henceforth.
56
57       SNMP  sessions  that are created with snmp_sess_open() are not affected
58       by, and SHOULD  NOT  BE  USED  WITH,  snmp_select_info(),  snmp_read(),
59       snmp_timeout()  nor snmp_close().  Rather the equivalent single session
60       functions described here should be used.
61
62       snmp_sess_init() and snmp_sess_open() each take as input a pointer to a
63       struct  snmp_session object.  This structure contains information for a
64       set of transactions that will share similar transport  characteristics.
65       snmp_sess_session()  takes  the  opaque  session  handle  and returns a
66       pointer to its associated struct snmp_session.
67
68       snmp_sess_send() and snmp_sess_async_send() each take a pdu  parameter,
69       which  points  to  a struct snmp_pdu object containing information that
70       describes a transaction that will be performed over an open session.
71
72       Consult snmp_api.h for the definitions of these structures.
73
74       snmp_sess_select_info(), snmp_sess_read() and snmp_sess_timeout()  pro‐
75       vide an interface for the use of the select(2) system call so that SNMP
76       transactions for a single session can occur asynchronously.
77
78       snmp_sess_select_info() is passed the information that would have  been
79       passed  to  select(2)  in the absence of SNMP.  For example, this might
80       include file descriptors associated with the main loop of  a  graphical
81       application.  This  information  is  modified so that SNMP will get the
82       service it requires from the call to select(2).  In this case,  numfds,
83       fdset and timeout correspond to the nfds, readfds and timeout arguments
84       to select(2) respectively.  The only exception  is  that  timeout  must
85       ALWAYS point to an allocated (but perhaps uninitialized) struct timeval
86       (it cannot be NULL as for  select(2)).   If  timeout  would  have  been
87       passed as NULL, block is instead set to true, and timeout is treated as
88       undefined.  This same rule applies upon return from snmp_select_info().
89
90       After calling snmp_sess_select_info() , select(2) should be called with
91       the  returned  data.   When it returns, snmp_sess_read() should then be
92       called with the fd_set returned from select(2).   This  will  read  any
93       input  from  this  session's SNMP socket.  If select(2) times out (that
94       is, it returns zero), snmp_sess_timeout() should be called to see if  a
95       timeout has occurred on the SNMP session.
96

DIAGNOSTICS

98       Error  return  status from snmp_sess_open() is indicated by return of a
99       NULL  pointer.   Error  return  status   from   snmp_sess_close()   and
100       snmp_sess_send()  is  indicated  by  a return value of 0.  A successful
101       status will return 1.
102
103       Further information can be obtained by using snmp_sess_error()  to  see
104       what  type  of  error  has  occurred.   This  function returns the SNMP
105       snmp_errno variable, the value of the  system  errno  variable,  and  a
106       string  interpretation  of  both  variables.   The string must be freed
107       after use by the caller.
108
109       For errors returned by snmp_sess_open(), use the corresponding function
110       snmp_error() instead of snmp_sess_error().
111
112       Consult  snmp_api.h  for the complete set of SNMP library error values.
113       The SNMP library error value snmperr can be one of the  following  val‐
114       ues:
115
116         SNMPERR_GENERR           A generic error occurred.
117
118         SNMPERR_BAD_LOCPORT      The  local  port  was  bad  because  it  had
119                                  already been  allocated  or  permission  was
120                                  denied.
121
122         SNMPERR_BAD_ADDRESS      The  host name or address given was not use‐
123                                  able.
124
125         SNMPERR_BAD_SESSION      The specified session was not open.
126
127         SNMPERR_TOO_LONG
128
129         SNMPERR_NO_SOCKET
130
131         SNMPERR_V2_IN_V1
132
133         SNMPERR_V1_IN_V2
134
135         SNMPERR_BAD_REPEATERS
136
137         SNMPERR_BAD_REPETITIONS
138
139         SNMPERR_BAD_ASN1_BUILD
140
141         SNMPERR_BAD_SENDTO
142
143         SNMPERR_BAD_RCVFROM
144
145         SNMPERR_BAD_PARSE
146
147         SNMPERR_BAD_VERSION
148
149         SNMPERR_BAD_COMMUNITY
150
151         SNMPERR_NOAUTH_DESPRIV
152
153         SNMPERR_ABORT
154
155         SNMPERR_UNKNOWN_PDU
156
157         SNMPERR_TIMEOUT
158

SEE ALSO

160       select(2), snmp_api(3), snmp_api.h
161
162
163
1644.2 Berkeley Distribution         07 Mar 2002                 SNMP_SESS_API(3)
Impressum