283 lines
8.0 KiB
Modula-2
283 lines
8.0 KiB
Modula-2
.\" -*- nroff -*-
|
|
.\" Portions of this file are subject to the following copyright. See
|
|
.\" the Net-SNMP COPYING file for more details and other copyrights
|
|
.\" that may apply:
|
|
.\" /***********************************************************
|
|
.\" Copyright 1989 by Carnegie Mellon University
|
|
.\"
|
|
.\" All Rights Reserved
|
|
.\"
|
|
.\" Permission to use, copy, modify, and distribute this software and its
|
|
.\" documentation for any purpose and without fee is hereby granted,
|
|
.\" provided that the above copyright notice appear in all copies and that
|
|
.\" both that copyright notice and this permission notice appear in
|
|
.\" supporting documentation, and that the name of CMU not be
|
|
.\" used in advertising or publicity pertaining to distribution of the
|
|
.\" software without specific, written prior permission.
|
|
.\"
|
|
.\" CMU DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
|
|
.\" ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL
|
|
.\" CMU BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR
|
|
.\" ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
|
|
.\" WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
|
|
.\" ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
|
|
.\" SOFTWARE.
|
|
.\" ******************************************************************/
|
|
.TH NETSNMP_SESSION_API 3 "19 May 2011" VVERSIONINFO "Net-SNMP"
|
|
.SH NAME
|
|
snmp_sess_init,
|
|
snmp_open,
|
|
snmp_send,
|
|
snmp_async_send,
|
|
snmp_select_info,
|
|
snmp_read,
|
|
snmp_timeout,
|
|
snmp_synch_response,
|
|
snmp_close,
|
|
snmp_perror,
|
|
snmp_sess_perror,
|
|
snmp_error,
|
|
snmp_api_errstring \- netsnmp_session_api functions
|
|
.SH SYNOPSIS
|
|
.B #include <net-snmp/session_api.h>
|
|
.PP
|
|
.BI "void snmp_sess_init ( netsnmp_session*" "sess" );
|
|
.PP
|
|
.BI "netsnmp_session* snmp_open ( netsnmp_session *" "sess");
|
|
.RS
|
|
.I /* Input parameter not used in active sessions */
|
|
.RE
|
|
.PP
|
|
.BI "int snmp_send ( netsnmp_session *" "session,"
|
|
.RS
|
|
.BI "netsnmp_pdu *" "pdu" );
|
|
.RE
|
|
.PP
|
|
.BI "int snmp_async_send ( netsnmp_session *" "session,"
|
|
.RS
|
|
.BI " netsnmp_pdu *" pdu ", "
|
|
.br
|
|
.BI " snmp_callback " callback ", "
|
|
.br
|
|
.BI " void *" callbackData ");"
|
|
.RE
|
|
.PP
|
|
.BI "int snmp_select_info ( int * " numfds, "fd_set *" fdset,
|
|
.RS
|
|
.BI "struct timeval *" timeout, "int *" block );
|
|
.RE
|
|
.PP
|
|
.BI "void snmp_read ( fd_set *" fdset );
|
|
.PP
|
|
.B void snmp_timeout ( void );
|
|
.PP
|
|
.BI "int snmp_synch_response ( netsnmp_session *" "session,"
|
|
.RS
|
|
.BI "netsnmp_pdu *" "pdu" ", "
|
|
.br
|
|
.BI "netsnmp_pdu **" "response" );
|
|
.RE
|
|
.PP
|
|
.BI "int snmp_close ( netsnmp_session *" session );
|
|
.br
|
|
.B "int snmp_close_sessions ( void );
|
|
.PP
|
|
.SS Error Reporting
|
|
.I (Move to output_api(3))
|
|
.br
|
|
.BI "void snmp_error ( netsnmp_session *session,
|
|
.RS
|
|
.BI "int *" pcliberr, "int *" psnmperr, "char **" pperrstring );
|
|
.RE
|
|
.PP
|
|
.BI "char *snmp_api_errstring ( int" snmperr );
|
|
.PP
|
|
.BI "void snmp_perror ( char *" msg );
|
|
.RS
|
|
.I /* for parsing errors only */
|
|
.RE
|
|
.PP
|
|
.BI "void snmp_sess_perror (char *" msg, "netsnmp_session *" sess );
|
|
.RS
|
|
.I /* all other SNMP library errors */
|
|
.RE
|
|
.PP
|
|
.SH DESCRIPTION
|
|
.I Snmp_sess_init
|
|
prepares a netsnmp_session that sources transport characteristics
|
|
and common information that will be used for a set of SNMP transactions.
|
|
After this structure is passed to
|
|
.I snmp_open
|
|
to create an SNMP session, the structure is not used.
|
|
.PP
|
|
.I Snmp_open
|
|
returns a pointer to a newly-formed
|
|
.I netsnmp_session
|
|
object, which the application must use to reference the
|
|
active SNMP session.
|
|
.PP
|
|
.I snmp_send
|
|
and
|
|
.I snmp_async_send()
|
|
each take as input a pointer to a
|
|
.I netsnmp_pdu
|
|
object.
|
|
This structure contains 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_async_send()
|
|
call,
|
|
.I snmp_read
|
|
will invoke the specified callback when the response is received.
|
|
.PP
|
|
.I Snmp_read, snmp_select_info,
|
|
and
|
|
.I snmp_timeout
|
|
provide an interface for the use of the
|
|
.IR select(2)
|
|
system call so that SNMP transactions can occur asynchronously.
|
|
.PP
|
|
.I Snmp_select_info
|
|
is given the information that would have been passed to
|
|
.I select
|
|
in the absence of SNMP. For example, this might include window update information.
|
|
This information is modified so that SNMP will get the service it requires from the
|
|
call to
|
|
.I select.
|
|
In this case,
|
|
.I numfds, fdset,
|
|
and
|
|
.I timeout
|
|
correspond to the
|
|
.I nfds, readfds,
|
|
and
|
|
.I timeout
|
|
arguments to
|
|
.I select,
|
|
respectively. The only exception is that timeout must always point to an allocated (but perhaps uninitialized)
|
|
.I struct timeval.
|
|
If
|
|
.I timeout
|
|
would have been passed as NULL,
|
|
.I block
|
|
is set to true, and
|
|
.I timeout
|
|
is treated as undefined. This same rule applies upon return from
|
|
.I snmp_select_info.
|
|
.PP
|
|
After calling
|
|
.I snmp_select_info, select
|
|
is called with the returned data. When select returns,
|
|
.I snmp_read
|
|
should be called with the
|
|
.I fd_set
|
|
returned from
|
|
.I select
|
|
to read each SNMP socket that has input.
|
|
If
|
|
.I select
|
|
times out,
|
|
.I snmp_timeout
|
|
should be called to see if the timeout was intended for SNMP.
|
|
.PP
|
|
.I snmp_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_send" ", " "snmp_read"
|
|
etc for details.
|
|
.SH DIAGNOSTICS
|
|
.PP
|
|
Previous versions of the library used
|
|
.IR snmp_get_errno
|
|
to read the global variable
|
|
.I snmp_errno
|
|
which may have held the error status within the SNMP library.
|
|
The existing method
|
|
.I snmp_perror
|
|
should be used to log ASN.1 coding errors only.
|
|
.PP
|
|
The new method
|
|
.I snmp_sess_perror
|
|
is provided to capture errors that occur during the processing
|
|
of a particular SNMP session.
|
|
.I Snmp_sess_perror
|
|
calls
|
|
.IR snmp_error
|
|
function to obtain the "C" library error
|
|
.I errno
|
|
, the SNMP library error
|
|
.I snmperr
|
|
, and the SNMP library detailed error message
|
|
that is associated with an error that occurred during a given session.
|
|
.PP
|
|
Note that in all cases except one,
|
|
.IR snmp_sess_perror
|
|
should be handed the
|
|
.I netsnmp_session *
|
|
pointer returned from
|
|
.IR snmp_open.
|
|
If
|
|
.IR snmp_open
|
|
returns a null pointer, pass the INPUT
|
|
.I netsnmp_session *
|
|
pointer used to call
|
|
.IR snmp_open.
|
|
.PP
|
|
Error return status from
|
|
.I snmp_close
|
|
and
|
|
.I snmp_send
|
|
is indicated by return of 0. A successful status will return a 1 for
|
|
.I snmp_close
|
|
and the request id of the packet for
|
|
.I snmp_send.
|
|
Upon successful return from
|
|
.I snmp_send
|
|
the pdu will be freed by the library.
|
|
.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_PARSE \w'SNMPERR_BAD_REPETITIONS'u+2n
|
|
.IP SNMPERR_BAD_VERSION \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
|
|
A string representation of the error code can be obtained with
|
|
.IR snmp_api_errstring ,
|
|
and a standard error message may be printed using
|
|
.I snmp_perror
|
|
that functions like the
|
|
.I perror
|
|
standard routine.
|
|
.SH "SEE ALSO"
|
|
select(2), netsnmp_sess_api(3), netsnmp_mib_api(3), netsnmp_pdu_api(3),
|
|
netsnmp_varbind_api(3), snmp_api.h
|