SNMPAPI(3)                        Net-SNMP                        SNMPAPI(3)



NAME
       snmpsessinit,  snmpopen, snmpsend, snmpfreepdu, snmpselectinfo,
       snmpread,  snmptimeout,  snmpclose,  snmpperror,  snmpsessperror,
       snmperror, snmpapierrstring - send and receive SNMP messages

SYNOPSIS
       #include 

       void snmpsessinit ( struct snmpsession * );

       struct snmpsession * snmpopen ( struct snmpsession *);
              /** Input parameter not used in active sessions **/

       int snmpsend ( struct snmpsession *session,
              struct snmppdu *pdu );

       int snmpselectinfo ( int *numfds, fdset *fdset,
              struct timeval *timeout, int *block );

       void snmpread ( fdset *fdset );

       void snmptimeout ( void );

       int snmpclose ( struct snmpsession *session );

       void snmpfreepdu ( struct snmppdu *pdu );

       void snmperror ( struct snmpsession *session,
              int *pcliberr, int *psnmperr, char **pperrstring );

       char *snmpapierrstring ( int snmperr );

       void snmpperror ( char * msg );
              /** for parsing errors only **/

       void snmpsessperror (char * msg, struct snmpsession *);
              /** all other SNMP library errors **/


DESCRIPTION
       Snmpsessinit  prepares  a  struct snmpsession that sources transport
       characteristics and common information that will be used for a  set  of
       SNMP transactions.  After this structure is passed to snmpopen to cre-
       ate an SNMP session, the structure is not used.

       Snmpopen returns a  pointer  to  a  newly-formed  struct  snmpsession
       object,  which  the  application  must use to reference the active SNMP
       session.

       Snmpsend and snmpfreepdu each take as input a pointer  to  a  struct
       snmppdu  object.  This structure contains information that describes a
       transaction that will be performed over an open session.

       Consult snmpapi.h for the definitions of these structures.

       Snmpread, snmpselectinfo, and snmptimeout provide an interface  for
       the  use  of  the  select(2)  system call so that SNMP transactions can
       occur asynchronously.

       Snmpselectinfo is given the information that would have  been  passed
       to select in the absence of SNMP.  For example, this might include win-
       dow update information.  This information is modified so that SNMP will
       get  the  service  it  requires from the call to select.  In this case,
       numfds, fdset, and timeout correspond to the nfds, readfds, and timeout
       arguments  to select, respectively.  The only exception is that timeout
       must always point to an allocated (but  perhaps  uninitialized)  struct
       timeval.   If  timeout  would have been passed as NUL, block is set to
       true, and timeout is treated as undefined.  This same rule applies upon
       return from snmpselectinfo.

       After  calling  snmpselectinfo,  select  is  called with the returned
       data.  When select returns, snmpread should be called with the  fdset
       returned  from  select  to  read  each  SNMP socket that has input.  If
       select times out, snmptimeout should be called to see if  the  timeout
       was intended for SNMP.

DIAGNOSTICS
       Previous versions of the library used snmpgeterrno to read the global
       variable snmperrno which may have held the  error  status  within  the
       SNMP  library.   The  existing method snmpperror should be used to log
       ASN.1 coding errors only.

       The new method snmpsessperror is  provided  to  capture  errors  that
       occur   during   the   processing   of   a   particular  SNMP  session.
       Snmpsessperror calls snmperror function to obtain  the  "C"  library
       error  errno  ,  the  SNMP library error snmperr , and the SNMP library
       detailed error message that is associated with an error  that  occurred
       during a given session.

       Note  that  in  all cases except one, snmpsessperror should be handed
       the  struct  snmpsession  *  pointer  returned  from  snmpopen.    If
       snmpopen  returns a null pointer, pass the INPUT struct snmpsession *
       pointer used to call snmpopen.

       Error return status from  snmpclose  and  snmpsend  is  indicated  by
       return  of  0.   A successful status will return a 1 for snmpclose and
       the request id of the packet for  snmpsend.   Upon  successful  return
       from snmpsend the pdu will be freed by the library.

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

         SNMPERGENER           A generic error occurred.

         SNMPERBADLOCPORT      The  local  port  was  bad  because  it  had
                                  already been  allocated  or  permission  was
                                  denied.

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

         SNMPERBADSESION      The specified session was not open.

         SNMPERTOLONG

         SNMPERNOSOCKET

         SNMPERV2INV1

         SNMPERV1INV2

         SNMPERBADREPEATERS

         SNMPERBADREPETITIONS

         SNMPERBADASN1BUILD

         SNMPERBADSENDTO

         SNMPERBADPARSE

         SNMPERBADVERSION

         SNMPERNOAUTHDESPRIV

         SNMPERABORT

         SNMPERUNKNOWNPDU

         SNMPERTIMEOUT

       A string  representation  of  the  error  code  can  be  obtained  with
       snmpapierrstring,  and  a standard error message may be printed using
       snmpperror that functions like the perror standard routine.

SEE ALSO
       select(2), snmpapi.h



4.2 Berkeley Distribution         21 Oct 1999                      SNMPAPI(3)