--- /dev/null
+.\" /***********************************************************
+.\" 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 SNMP_API 3 "21 Oct 1999" VVERSIONINFO "Net-SNMP"
+.UC 5
+.SH NAME
+snmp_sess_init, snmp_open, snmp_send, snmp_free_pdu, snmp_select_info, snmp_read, snmp_timeout, snmp_close, snmp_perror, snmp_sess_perror, snmp_error, snmp_api_errstring \- send and receive SNMP messages
+.SH SYNOPSIS
+#include <net-snmp/session_api.h>
+.PP
+void snmp_sess_init ( struct snmp_session * );
+.PP
+struct snmp_session * snmp_open ( struct snmp_session *);
+.RS
+.B /* Input parameter not used in active sessions */
+.RE
+.PP
+int snmp_send ( struct snmp_session *session,
+.RS
+struct snmp_pdu *pdu );
+.RE
+.PP
+int snmp_select_info ( int *numfds, fd_set *fdset,
+.RS
+struct timeval *timeout, int *block );
+.RE
+.PP
+void snmp_read ( fd_set *fdset );
+.PP
+void snmp_timeout ( void );
+.PP
+int snmp_close ( struct snmp_session *session );
+.PP
+void snmp_free_pdu (
+struct snmp_pdu *pdu );
+.PP
+void snmp_error (
+struct snmp_session *session,
+.RS
+int *pcliberr,
+int *psnmperr,
+char **pperrstring );
+.RE
+.PP
+char *snmp_api_errstring ( int snmperr );
+.PP
+void snmp_perror ( char * msg );
+.RS
+.B /* for parsing errors only */
+.RE
+.PP
+void snmp_sess_perror (char * msg, struct snmp_session *);
+.RS
+.B /* all other SNMP library errors */
+.RE
+.PP
+.SH DESCRIPTION
+.I 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
+.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 struct snmp_session
+object, which the application must use to reference the
+active SNMP session.
+.PP
+.I Snmp_send
+and
+.I snmp_free_pdu
+each take as input a pointer to a
+.I struct snmp_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
+.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.
+.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 struct snmp_session *
+pointer returned from
+.IR snmp_open.
+If
+.IR snmp_open
+returns a null pointer, pass the INPUT
+.I struct snmp_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 then 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), snmp_api.h
projects / bcm963xx.git / blobdiff