237 lines
7.2 KiB
Modula-2
237 lines
7.2 KiB
Modula-2
.TH NETSNMP_SESS_API 3 "19 May 2011" VVERSIONINFO "Net-SNMP"
|
|
.SH NAME
|
|
snmp_sess_init,
|
|
snmp_sess_open,
|
|
snmp_sess_session,
|
|
snmp_sess_send,
|
|
snmp_sess_async_send,
|
|
snmp_sess_select_info,
|
|
snmp_sess_read,
|
|
snmp_sess_timeout,
|
|
snmp_sess_synch_response,
|
|
snmp_sess_close,
|
|
snmp_sess_error - session functions
|
|
.SH SYNOPSIS
|
|
.B #include <net-snmp/session_api.h>
|
|
.PP
|
|
.BI "void snmp_sess_init(struct snmp_session *" session ");"
|
|
.PP
|
|
.BI "void *snmp_sess_open(struct snmp_session *" session ");"
|
|
.PP
|
|
.BI "struct snmp_session *snmp_sess_session(void *" handle ");"
|
|
.PP
|
|
.BI "int snmp_sess_send(void *" handle ", struct snmp_pdu *" pdu ");"
|
|
.PP
|
|
.BI "int snmp_sess_async_send(void *" handle ","
|
|
.br
|
|
.BI " struct snmp_pdu *" pdu ", "
|
|
.br
|
|
.BI " snmp_callback " callback ", "
|
|
.br
|
|
.BI " void *" callbackData ");"
|
|
.PP
|
|
.BI "int snmp_sess_select_info(void *" handle ","
|
|
.br
|
|
.BI " int *" numfds ", fd_set *" fdset ", "
|
|
.br
|
|
.BI " struct timeval *" timeout ", "
|
|
.br
|
|
.BI " int *" block ");"
|
|
.PP
|
|
.BI "int snmp_sess_read(void *" handle ", fd_set *" fdset ");"
|
|
.PP
|
|
.BI "void snmp_sess_timeout(void *" handle ");"
|
|
.PP
|
|
.BI "int snmp_sess_synch_response ( void *" "handle,"
|
|
.RS
|
|
.BI "netsnmp_pdu *" "pdu" ", "
|
|
.br
|
|
.BI "netsnmp_pdu **" "response" );
|
|
.RE
|
|
.PP
|
|
.BI "int snmp_sess_close(void *" handle ");"
|
|
.PP
|
|
.BI "void snmp_sess_error(void *" handle ", int *" pcliberr ", "
|
|
.br
|
|
.BI " int *" psnmperr ", char **" pperrstring ");"
|
|
.SH DESCRIPTION
|
|
These functions define a subset of the API that can be used
|
|
to manage single SNMP sessions in a multi-threaded application.
|
|
Except for
|
|
.BR snmp_sess_session() ,
|
|
these functions are single session versions of the traditional
|
|
SNMP library API.
|
|
.PP
|
|
Note that these functions use an opaque pointer
|
|
.RI ( handle
|
|
in the above prototypes) to identify a single session in lieu of a
|
|
.I session
|
|
pointer (as in the traditional API).
|
|
.PP
|
|
.B snmp_sess_init()
|
|
prepares a struct snmp_session that sources transport characteristics
|
|
and common information that will be used for a set of SNMP transactions.
|
|
After this structure is passed to
|
|
.B snmp_sess_open()
|
|
to create an SNMP session, the structure is no longer used. Instead
|
|
the opaque pointer returned by
|
|
.B snmp_sess_open()
|
|
is used to refer to that session henceforth.
|
|
.PP
|
|
SNMP sessions that are created with
|
|
.B snmp_sess_open()
|
|
are not affected by, and SHOULD NOT BE USED WITH,
|
|
.BR snmp_select_info() ", " snmp_read() ", " snmp_timeout() " nor"
|
|
.BR snmp_close() .
|
|
Rather the equivalent single session functions described here should
|
|
be used.
|
|
.PP
|
|
.B snmp_sess_init()
|
|
and
|
|
.B snmp_sess_open()
|
|
each take as input a pointer to a struct snmp_session object.
|
|
This structure contains information for a set of transactions that
|
|
will share similar transport characteristics.
|
|
.B snmp_sess_session()
|
|
takes the opaque session handle and returns a pointer to
|
|
its associated struct snmp_session.
|
|
.PP
|
|
.B snmp_sess_send()
|
|
and
|
|
.B snmp_sess_async_send()
|
|
each take a
|
|
.I pdu
|
|
parameter, which points to a struct snmp_pdu object containing
|
|
information that describes a transaction that will be performed over
|
|
an open session.
|
|
.PP
|
|
Consult snmp_api.h for the definitions of these structures.
|
|
.PP
|
|
With the
|
|
.I snmp_sess_async_send()
|
|
call,
|
|
.I snmp_sess_read
|
|
will invoke the specified callback when the response is received.
|
|
.PP
|
|
.BR snmp_sess_select_info() ", " snmp_sess_read() " and " snmp_sess_timeout()
|
|
provide an interface for the use of the
|
|
.BR select (2)
|
|
system call so that SNMP transactions for a single session can occur
|
|
asynchronously.
|
|
.PP
|
|
.B snmp_sess_select_info()
|
|
is passed the information that would have been passed to
|
|
.BR select (2)
|
|
in the absence of SNMP. For example, this might include file
|
|
descriptors associated with the main loop of a graphical
|
|
application. This information is modified so that SNMP will get the
|
|
service it requires from the call to
|
|
.BR select (2).
|
|
In this case,
|
|
.IR numfds ", " fdset " and " timeout
|
|
correspond to the
|
|
.IR nfds ", " readfds " and " timeout
|
|
arguments to
|
|
.BR select (2)
|
|
respectively. The only exception is that timeout must ALWAYS point to
|
|
an allocated (but perhaps uninitialized)
|
|
.I struct timeval
|
|
(it cannot be NULL as for
|
|
.BR select (2)).
|
|
If
|
|
.I timeout
|
|
would have been passed as NULL,
|
|
.I block
|
|
is instead set to true, and
|
|
.I timeout
|
|
is treated as undefined. This same rule applies upon return from
|
|
.BR snmp_select_info() .
|
|
.PP
|
|
After calling
|
|
.B snmp_sess_select_info() ,
|
|
.BR select (2)
|
|
should be called with the returned data. When it returns,
|
|
.B snmp_sess_read()
|
|
should then be called with the
|
|
.I fd_set
|
|
returned from
|
|
.BR select (2).
|
|
This will read any input from this session's SNMP socket. If
|
|
.BR select (2)
|
|
times out (that is, it returns zero),
|
|
.B snmp_sess_timeout()
|
|
should be called to see if a timeout has occurred on the SNMP
|
|
session.
|
|
.PP
|
|
.I snmp_sess_synch_response
|
|
is a convenience routine that will send the request,
|
|
wait for the response and process it before returning.
|
|
See the descriptions of
|
|
.I "snmp_sess_send" ", " "snmp_sess_read"
|
|
etc for details.
|
|
.SH DIAGNOSTICS
|
|
.PP
|
|
Error return status from
|
|
.B snmp_sess_open()
|
|
is indicated by return of a NULL pointer.
|
|
Error return status from
|
|
.B snmp_sess_close()
|
|
and
|
|
.B snmp_sess_send()
|
|
is indicated by a return value of 0. A successful status will return
|
|
1.
|
|
.PP
|
|
Further information can be obtained by using
|
|
.B snmp_sess_error()
|
|
to see what type of error has occurred. This function returns the
|
|
SNMP
|
|
.I snmp_errno
|
|
variable, the value of the system
|
|
.I errno
|
|
variable, and a string interpretation of both variables. The string
|
|
must be freed after use by the caller.
|
|
.PP
|
|
For errors returned by
|
|
.BR snmp_sess_open() ,
|
|
use the corresponding function
|
|
.B snmp_error()
|
|
instead of
|
|
.BR snmp_sess_error() .
|
|
.PP
|
|
Consult snmp_api.h for the complete set of SNMP library
|
|
error values.
|
|
The SNMP library error value
|
|
.IR snmperr
|
|
can be one of the following values:
|
|
.RS 2n
|
|
.IP SNMPERR_GENERR \w'SNMPERR_BAD_REPETITIONS'u+2n
|
|
A generic error occurred.
|
|
.IP SNMPERR_BAD_LOCPORT \w'SNMPERR_BAD_REPETITIONS'u+2n
|
|
The local port was bad because it had already been
|
|
allocated or permission was denied.
|
|
.IP SNMPERR_BAD_ADDRESS \w'SNMPERR_BAD_REPETITIONS'u+2n
|
|
The host name or address given was not useable.
|
|
.IP SNMPERR_BAD_SESSION \w'SNMPERR_BAD_REPETITIONS'u+2n
|
|
The specified session was not open.
|
|
.IP SNMPERR_TOO_LONG \w'SNMPERR_BAD_REPETITIONS'u+2n
|
|
.IP SNMPERR_NO_SOCKET \w'SNMPERR_BAD_REPETITIONS'u+2n
|
|
.IP SNMPERR_V2_IN_V1 \w'SNMPERR_BAD_REPETITIONS'u+2n
|
|
.IP SNMPERR_V1_IN_V2 \w'SNMPERR_BAD_REPETITIONS'u+2n
|
|
.IP SNMPERR_BAD_REPEATERS \w'SNMPERR_BAD_REPETITIONS'u+2n
|
|
.IP SNMPERR_BAD_REPETITIONS \w'SNMPERR_BAD_REPETITIONS'u+2n
|
|
.IP SNMPERR_BAD_ASN1_BUILD \w'SNMPERR_BAD_REPETITIONS'u+2n
|
|
.IP SNMPERR_BAD_SENDTO \w'SNMPERR_BAD_REPETITIONS'u+2n
|
|
.IP SNMPERR_BAD_RCVFROM \w'SNMPERR_BAD_REPETITIONS'u+2n
|
|
.IP SNMPERR_BAD_PARSE \w'SNMPERR_BAD_REPETITIONS'u+2n
|
|
.IP SNMPERR_BAD_VERSION \w'SNMPERR_BAD_REPETITIONS'u+2n
|
|
.IP SNMPERR_BAD_COMMUNITY \w'SNMPERR_BAD_REPETITIONS'u+2n
|
|
.IP SNMPERR_NOAUTH_DESPRIV \w'SNMPERR_BAD_REPETITIONS'u+2n
|
|
.IP SNMPERR_ABORT \w'SNMPERR_BAD_REPETITIONS'u+2n
|
|
.IP SNMPERR_UNKNOWN_PDU \w'SNMPERR_BAD_REPETITIONS'u+2n
|
|
.IP SNMPERR_TIMEOUT \w'SNMPERR_BAD_REPETITIONS'u+2n
|
|
.RE
|
|
.PP
|
|
.SH "SEE ALSO"
|
|
select(2), netsnmp_session_api(3), netsnmp_pdu_api(3),
|
|
netsnmp_varbind_api(3), netsnmp_mib_api(3), snmp_api.h
|