---
name: "sk_new_session"
section: "3"
platform: "linux"
package: "libsnmpkit-dev"
version: "0.9-16"
release: "Debian 8 (Jessie)"
platforms: ["linux"]
url: "https://new.carta.tech/sk_new_session"
---

# sk\_new\_session(3)

create a new SNMPSESSION

## NAME

sk\_new\_session - create a new SNMPSESSION

## SYNOPSIS

**#include \<snmpkit.h\>**

**SNMPSESSION \*sk\_new\_session(char \****host***, void \*(***start\_routine***)(SNMPSESSION\*), const char \****community***);**

**SNMPSESSION \*\*sk\_new\_sessions(char \****hostspec***,const char \****community***,void \*(***start\_routine***)(SNMPSESSION\*));**

**SNMPSESSION \*\*sk\_new\_sessions\_multi(char \*\****hostspecs***, const char \****community***, void \*(***start\_routine***)(SNMPSESSION\*));**

## DESCRIPTION

An **SNMP\_session** instance is an object that handles the details of communicating an SNMP enabled device such as a printer or a router.

There are three versions of sk\_new\_sessions. They two of the parmeters are identical. The first one varies between the different versions of the function.

A SNMP community string acts as a password.  Normally there are two strings set for an SNMP enabled device.  One will allow the user write access to settings via SNMP commands and the second password will only allow for read access to device settings.

You must also provide a pointer to the start\_routine function.  The start\_routine() is the function used to actually do the work of communicating with the network device. In other words, this function is called when the thread handling this particular device is activated. In other words, this function actually loads up the packets with the SNMP objects and then makes the requsts. Each SNMPSESSION has its own thread and once the thread is created. When the start\_function function is called, it is passed the SNMPSESSION pointer as a paramter.

The first parameter varies between the functions. In the case of sk\_new\_session it is simply a hostname in a format understood by **[gethostbyname(3)](/gethostbyname/3.md)**. In the case of sk\_new\_sessions, instead of a simple hostname a hostspec is passed in. A hostspec can be a simple hostname but it can also be an IP address range in the form of 192.168.0.1-5 or an IP address and a subnet mask in the form of either 192.168.0.0/255.255.255.0 or 192.168.0.0/24. A hostspec may also include a community name by enclosing that in parenthesis like 192.168.0.1(public).

## RETURN VALUE

Upon successful completion sk\_new\_session returns a pointer to a SNMPSESSION. sk\_new\_sessions and sk\_new\_sessions\_multi both return a null terminated array of SNMPSESSION pointers. Otherwise NULL is returned and sk\_errno is set to indicate the error.

## ERRORS

- **SK\_MEM\_FAIL**

  Memory allocation failed.

- **SK\_BAD\_PROTO**

  UDP protocol is not supported. See **[getprotobyname(3)](/getprotobyname/3.md)**.

- **SK\_SOCKET\_FAIL**

  Can't create socket. See **[socket(2)](/socket/2.md)**.

- **SK\_RECEIVER\_FAIL**

  Can't create a thread to receive packets. Sets errno. See **[pthread\_create(3)](/pthread_create/3.md)**.

- **SK\_HOSTNOTFOUND**

  Host not found. Sets h\_errno. See **[gethostbyname(3)](/gethostbyname/3.md)**.

- **SK\_REAPER\_FAIL**

  Can't create a thread to reap spent threads. Sets errno. See **[pthread\_create(3)](/pthread_create/3.md)**.

- **SK\_WORKER\_FAIL**

  Can't create worker thread. Sets errno. See **[pthread\_create(3)](/pthread_create/3.md)**.

- **SK\_UNTERM\_HOSPEC**

  Community in hostspec doesn't have ending parenthesis.

- **SK\_OCTET\_OVERFLOW**

  One of the octets in hostspec is greater than 255.

- **SK\_BAD\_NETMASK**

  Subnet mask wasn't in a understood form.

- **SK\_NETMASK\_OVERFLOW**

  Number of bits in subnet mask is too large.

- **SK\_DIS\_NETMASK**

  Subnet mask had discontinious bits.

## SEE ALSO

sk\_strerror(3), sk\_snmpsessions\_done(3), sk\_new\_sfiller(3), sk\_new\_snmptable(3)