| .\" /*********************************************************** |
| .\" 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 "19 May 2011" VVERSIONINFO "Net-SNMP" |
| .SH NAME |
| snmp_sess_init, snmp_open, snmp_send, snmp_async_send, snmp_free_pdu, snmp_select_info, snmp_read, snmp_timeout, snmp_synch_response, 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_async_send ( struct snmp_session *session, |
| .RS |
| struct snmp_pdu *pdu, |
| snmp_callback callback, |
| void *callbackData ); |
| .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_synch_response ( struct snmp_session *session, |
| .RS |
| struct snmp_pdu *pdu, |
| struct snmp_pdu **response); |
| .RE |
| .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, snmp_async_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 |
| 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 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 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), snmp_api.h |