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 *);
              //** IInnppuutt ppaarraammeetteerr nnoott uusseedd iinn aaccttiivvee sseessssiioonnss **//

       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 );
              //** ffoorr ppaarrssiinngg eerrrroorrss oonnllyy **//

       void snmpsessperror (char * msg, struct snmpsession *);
              //** aallll ootthheerr SSNNMMPP lliibbrraarryy eerrrroorrss **//


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 NULL, 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:

         SNMPERRGENERR           A generic error occurred.

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

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

         SNMPERRBADSESSION      The specified session was not open.

         SNMPERRTOOLONG

         SNMPERRNOSOCKET

         SNMPERRV2INV1

         SNMPERRV1INV2

         SNMPERRBADREPEATERS

         SNMPERRBADREPETITIONS

         SNMPERRBADASN1BUILD

         SNMPERRBADSENDTO

         SNMPERRBADPARSE

         SNMPERRBADVERSION

         SNMPERRNOAUTHDESPRIV

         SNMPERRABORT

         SNMPERRUNKNOWNPDU

         SNMPERRTIMEOUT

       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)