--- name: "netsnmp_session_api" section: "3" platform: "linux" package: "net-snmp" version: "5.9.5.2-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/netsnmp_session_api" --- # netsnmp\_session\_api(3) netsnmp\_session\_api functions ## NAME snmp\_sess\_init, snmp\_open, snmp\_send, snmp\_async\_send, snmp\_select\_info, snmp\_read, snmp\_timeout, snmp\_synch\_response, snmp\_close, snmp\_perror, snmp\_sess\_perror, snmp\_error, snmp\_api\_errstring - netsnmp\_session\_api functions ## SYNOPSIS **#include \** **void snmp\_sess\_init ( netsnmp\_session\****sess***);** **netsnmp\_session\* snmp\_open ( netsnmp\_session \****sess***);** */\* Input parameter not used in active sessions \*/* **int snmp\_send ( netsnmp\_session \****session,* **netsnmp\_pdu \****pdu***);** **int snmp\_async\_send ( netsnmp\_session \****session,* **netsnmp\_pdu \****pdu***,** \ **snmp\_callback** *callback***,** \ **void \****callbackData***);** **int snmp\_select\_info ( int \*** *numfds,***fd\_set \****fdset,* **struct timeval \****timeout,***int \****block***);** **void snmp\_read ( fd\_set \****fdset***);** **void snmp\_timeout ( void );** **int snmp\_synch\_response ( netsnmp\_session \****session,* **netsnmp\_pdu \****pdu***,** \ **netsnmp\_pdu \*\****response***);** **int snmp\_close ( netsnmp\_session \****session***);**\ **int snmp\_close\_sessions ( void );** ### Error Reporting *(Move to output\_api(3))*\ **void snmp\_error ( netsnmp\_session \*session,** **int \****pcliberr,***int \****psnmperr,***char \*\****pperrstring***);** **char \*snmp\_api\_errstring ( int***snmperr***);** **void snmp\_perror ( char \****msg***);** */\* for parsing errors only \*/* **void snmp\_sess\_perror (char \****msg,***netsnmp\_session \****sess***);** */\* all other SNMP library errors \*/* ## DESCRIPTION *Snmp\_sess\_init* prepares a netsnmp\_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\_open* to create an SNMP session, the structure is not used. *Snmp\_open* returns a pointer to a newly-formed *netsnmp\_session* object, which the application must use to reference the active SNMP session. *snmp\_send* and *snmp\_async\_send()* each take as input a pointer to a *netsnmp\_pdu* object. This structure contains 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\_async\_send()* call, *snmp\_read* will invoke the specified callback when the response is received. *Snmp\_read, snmp\_select\_info,* and *snmp\_timeout* provide an interface for the use of the *[select(2)](/select/2.md)* system call so that SNMP transactions can occur asynchronously. *Snmp\_select\_info* is given the information that would have been passed to *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 *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 *snmp\_select\_info.* After calling *snmp\_select\_info, select* is called with the returned data. When select returns, *snmp\_read* should be called with the *fd\_set* returned from *select* to read each SNMP socket that has input. If *select* times out, *snmp\_timeout* should be called to see if the timeout was intended for SNMP. *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 *snmp\_send , snmp\_read* etc for details. ## DIAGNOSTICS Previous versions of the library used *snmp\_get\_errno* to read the global variable *snmp\_errno* which may have held the error status within the SNMP library. The existing method *snmp\_perror* should be used to log ASN.1 coding errors only. The new method *snmp\_sess\_perror* is provided to capture errors that occur during the processing of a particular SNMP session. *Snmp\_sess\_perror* calls *snmp\_error* 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, *snmp\_sess\_perror* should be handed the *netsnmp\_session \** pointer returned from *snmp\_open.* If *snmp\_open* returns a null pointer, pass the INPUT *netsnmp\_session \** pointer used to call *snmp\_open.* Error return status from *snmp\_close* and *snmp\_send* is indicated by return of 0. A successful status will return a 1 for *snmp\_close* and the request id of the packet for *snmp\_send.* Upon successful return from *snmp\_send* the pdu will be freed by the library. 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 values: - SNMPERR\_GENERR A generic error occurred. - SNMPERR\_BAD\_LOCPORT The local port was bad because it had already been allocated or permission was denied. - SNMPERR\_BAD\_ADDRESS The host name or address given was not useable. - 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\_PARSE - SNMPERR\_BAD\_VERSION - SNMPERR\_NOAUTH\_DESPRIV - SNMPERR\_ABORT - SNMPERR\_UNKNOWN\_PDU - SNMPERR\_TIMEOUT A string representation of the error code can be obtained with *snmp\_api\_errstring*, and a standard error message may be printed using *snmp\_perror* that functions like the *perror* standard routine. ## SEE ALSO [select(2)](/select/2.md), [netsnmp\_sess\_api(3)](/netsnmp_sess_api/3.md), [netsnmp\_mib\_api(3)](/netsnmp_mib_api/3.md), [netsnmp\_pdu\_api(3)](/netsnmp_pdu_api/3.md), [netsnmp\_varbind\_api(3)](/netsnmp_varbind_api/3.md), snmp\_api.h