Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
NETSNMP_SESS_API(3)		   Net-SNMP		   NETSNMP_SESS_API(3)

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

SYNOPSIS
       #include	<net-snmp/session_api.h>

       void snmp_sess_init(struct snmp_session *session);

       void *snmp_sess_open(struct snmp_session	*session);

       struct snmp_session *snmp_sess_session(void *handle);

       int snmp_sess_send(void *handle,	struct snmp_pdu	*pdu);

       int snmp_sess_async_send(void *handle,
				struct snmp_pdu	*pdu,
				snmp_callback callback,
				void *callbackData);

       int snmp_sess_select_info(void *handle,
				 int *numfds, fd_set *fdset,
				 struct	timeval	*timeout,
				 int *block);

       int snmp_sess_read(void *handle,	fd_set *fdset);

       void snmp_sess_timeout(void *handle);

       int snmp_sess_synch_response ( void *handle,
	      netsnmp_pdu *pdu,
	      netsnmp_pdu **response);

       int snmp_sess_close(void	*handle);

       void snmp_sess_error(void *handle, int *pcliberr,
			   int *psnmperr, char **pperrstring);

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
       snmp_sess_session(), these functions are	single session versions	of the
       traditional SNMP	library	API.

       Note  that  these  functions use	an opaque pointer (handle in the above
       prototypes) to identify a single	session	in lieu	of a  session  pointer
       (as in the traditional API).

       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 snmp_sess_open()
       to create an SNMP session, the structure	is no  longer  used.   Instead
       the  opaque  pointer  returned  by snmp_sess_open() is used to refer to
       that session henceforth.

       SNMP sessions that are created with snmp_sess_open() are	 not  affected
       by,  and	 SHOULD	 NOT  BE  USED	WITH, snmp_select_info(), snmp_read(),
       snmp_timeout() nor snmp_close().	 Rather	the equivalent single  session
       functions described here	should be used.

       snmp_sess_init()	and 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.
       snmp_sess_session() takes the  opaque  session  handle  and  returns  a
       pointer to its associated struct	snmp_session.

       snmp_sess_send()	 and snmp_sess_async_send() each take a	pdu parameter,
       which points to a struct	snmp_pdu object	 containing  information  that
       describes a transaction that will be performed over an open session.

       Consult snmp_api.h for the definitions of these structures.

       With  the  snmp_sess_async_send()  call,	snmp_sess_read will invoke the
       specified callback when the response is received.

       snmp_sess_select_info(),	snmp_sess_read() and snmp_sess_timeout()  pro-
       vide an interface for the use of	the select(2) system call so that SNMP
       transactions for	a single session can occur asynchronously.

       snmp_sess_select_info() is passed the information that would have  been
       passed  to  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 select(2).	In this	case,  numfds,
       fdset and timeout correspond to the nfds, readfds and timeout arguments
       to select(2) respectively.  The only exception is that timeout must AL-
       WAYS  point  to an allocated (but perhaps uninitialized)	struct timeval
       (it cannot be NULL as for  select(2)).	If  timeout  would  have  been
       passed as NULL, block is	instead	set to true, and timeout is treated as
       undefined.  This	same rule applies upon return from snmp_select_info().

       After calling snmp_sess_select_info() , select(2) should	be called with
       the  returned  data.   When it returns, snmp_sess_read()	should then be
       called with the fd_set returned from select(2).	This will read any in-
       put  from this session's	SNMP socket.  If select(2) times out (that is,
       it returns zero), snmp_sess_timeout() should be	called	to  see	 if  a
       timeout has occurred on the SNMP	session.

       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 snmp_sess_send ,  snmp_sess_read etc	for details.

DIAGNOSTICS
       Error  return  status from snmp_sess_open() is indicated	by return of a
       NULL  pointer.	Error  return  status	from   snmp_sess_close()   and
       snmp_sess_send()	 is  indicated	by  a return value of 0.  A successful
       status will return 1.

       Further information can be obtained by using snmp_sess_error()  to  see
       what  type  of  error  has  occurred.   This  function returns the SNMP
       snmp_errno variable, the	value of the  system  errno  variable,	and  a
       string  interpretation of both variables.  The string must be freed af-
       ter use by the caller.

       For errors returned by snmp_sess_open(),	use the	corresponding function
       snmp_error() instead of snmp_sess_error().

       Consult	snmp_api.h  for	the complete set of SNMP library error values.
       The SNMP	library	error value snmperr can	be one of the  following  val-
       ues:

	 SNMPERR_GENERR		  A generic error occurred.

	 SNMPERR_BAD_LOCPORT	  The  local  port  was	bad because it had al-
				  ready	been allocated or permission  was  de-
				  nied.

	 SNMPERR_BAD_ADDRESS	  The  host name or address given was not use-
				  able.

	 SNMPERR_BAD_SESSION	  The specified	session	was not	open.

	 SNMPERR_TOO_LONG

	 SNMPERR_NO_SOCKET

	 SNMPERR_V2_IN_V1

	 SNMPERR_V1_IN_V2

	 SNMPERR_BAD_REPEATERS

	 SNMPERR_BAD_REPETITIONS

	 SNMPERR_BAD_ASN1_BUILD

	 SNMPERR_BAD_SENDTO

	 SNMPERR_BAD_RCVFROM

	 SNMPERR_BAD_PARSE

	 SNMPERR_BAD_VERSION

	 SNMPERR_BAD_COMMUNITY

	 SNMPERR_NOAUTH_DESPRIV

	 SNMPERR_ABORT

	 SNMPERR_UNKNOWN_PDU

	 SNMPERR_TIMEOUT

SEE ALSO
       select(2),     netsnmp_session_api(3),	  netsnmp_pdu_api(3),	  net-
       snmp_varbind_api(3), netsnmp_mib_api(3),	snmp_api.h

V5.7.3				  19 May 2011		   NETSNMP_SESS_API(3)

NAME | SYNOPSIS | DESCRIPTION | DIAGNOSTICS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=snmp_sess_init&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help