NETSNMP_SESSION_API(3)

✨ NETSNMP_SESSION_API ✨

okay bestie, welcome to the netsnmp_session_api(3) page from Net-SNMP — this is the session-handling corner of the SNMP library and it's honestly a whole vibe. grab a strawberry 🍓 and let's get into it.

---

🌸 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 — these are the netsnmp_session_api functions 💅

---

🎀 SYNOPSIS 🎀

#include <net-snmp/session_api.h>

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 ( intsnmperr);

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

void snmp_sess_perror (char *msg,netsnmp_session *sess);
       /* all other SNMP library errors */

---

💖 DESCRIPTION 💖

so snmp_sess_init gets a netsnmp_session all prepped and ready — it sets up the transport characteristics plus the common info that a whole set of SNMP transactions is gonna use. 🧚 but listen: once you pass that structure to snmp_open to actually create an SNMP session, that structure is not used anymore. it's done, it served its purpose, it's retired, no cap.

snmp_open hands you back a pointer to a freshly-formed netsnmp_session object, and that's the one your application has to use to reference the active SNMP session. that's your main character now 👑

snmp_send and snmp_async_send() both take, as input, a pointer to a netsnmp_pdu object. that structure is carrying the info that describes a transaction that's gonna be performed over an open session. 📦

want the definitions of these structures? go look in snmp_api.h, bestie, they're all in there.

with the snmp_async_send() call, snmp_read will invoke the callback you specified when the response comes in. 🔔

snmp_read, snmp_select_info, and snmp_timeout are the trio that gives you an interface for using the select(2) system call, so your SNMP transactions can happen asynchronously. ✨

snmp_select_info gets handed the information that would have been passed to select if SNMP weren't in the picture. like, for example, maybe that info includes window update stuff. 🪟 that information gets modified so SNMP gets the service it needs out of the select call. in this case numfds, fdset, and timeout line up with the nfds, readfds, and timeout arguments to select, respectively. the one exception is that timeout has to always point to an allocated (but maybe uninitialized) struct timeval. if timeout would have been passed as NULL, then block gets set to true, and timeout is treated as undefined. same exact rule applies when snmp_select_info returns. 📝

after you call snmp_select_info, select gets called with the returned data. when select comes back, snmp_read should be called with the fd_set that select returned, so you can read each SNMP socket that has input. and if select times out, snmp_timeout should be called to check whether that timeout was actually meant for SNMP. ⏰

snmp_synch_response is the convenience routine — it sends the request, waits for the response, and processes it, all before it returns. it's giving ✨effortless✨. for the details, go read the descriptions of snmp_send, snmp_read, etc.

---

🩺 DIAGNOSTICS 🩺

so back in the day, previous versions of the library used snmp_get_errno to read the global variable snmp_errno, which may have been holding the error status inside the SNMP library. the method that exists now, snmp_perror, should be used to log ASN.1 coding errors only. 💀

the new method snmp_sess_perror is there to capture errors that happen while processing a particular SNMP session. snmp_sess_perror calls the snmp_error function to grab the "C" library error errno, the SNMP library error snmperr, and the SNMP library detailed error message that goes with an error that occurred during a given session. 🫶

okay important note: in all cases except one, snmp_sess_perror should be handed the netsnmp_session * pointer that snmp_open returned. but if snmp_open returns a null pointer, then pass the INPUT netsnmp_session * pointer you used to call snmp_open. don't get this twisted 🙈

error return status from snmp_close and snmp_send is indicated by a return of 0. a successful status will return a 1 for snmp_close, and the request id of the packet for snmp_send. upon a successful return from snmp_send, the pdu will be freed by the library. periodt. 💅

need the complete set of SNMP library error values? consult snmp_api.h.

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 can be printed using snmp_perror, which functions like the perror standard routine. 🌈

---

👀 SEE ALSO 👀

select(2), netsnmp_sess_api(3), netsnmp_mib_api(3), netsnmp_pdu_api(3), netsnmp_varbind_api(3), snmp_api.h

---

and that's the whole page, bestie 🦋 this one's from Net-SNMP version V5.9.5.2, dated 19 May 2011. iconic, legendary, no notes. go slay your sessions 👑💖