.TH SK_NEW_SESSION 3 "November 2000" "GNU snmpkit 0.4"
.SH NAME
sk_new_session \- create a new SNMPSESSION
.SH SYNOPSIS
.B #include <snmpkit.h>
.sp
.BI "SNMPSESSION *sk_new_session(char *" host ", void *(" start_routine ")(SNMPSESSION*), const char *" community ");"
.sp
.BI "SNMPSESSION **sk_new_sessions(char *" hostspec ",const char *" community ",void *(" start_routine ")(SNMPSESSION*));"
.sp
.BI "SNMPSESSION **sk_new_sessions_multi(char **" hostspecs ", const char *" community ", void *(" start_routine ")(SNMPSESSION*));"
.SH "DESCRIPTION"
An \fBSNMP_session\fP instance is an object that handles the details
of communicating an SNMP enabled device such as a printer or a
router.
.sp
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. 
.sp
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.
.sp
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.
.sp
The first parameter varies between the functions. In the case of
sk_new_session it is simply a hostname in a format understood by
\fBgethostbyname(3)\fP. 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). 
.SH "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.
.SH "ERRORS"
.TP
.B SK_MEM_FAIL 
Memory allocation failed.
.TP
.B SK_BAD_PROTO
UDP protocol is not supported. See \fBgetprotobyname(3)\fP.
.TP
.B SK_SOCKET_FAIL
Can't create socket. See \fBsocket(2)\fP.
.TP
.B SK_RECEIVER_FAIL
Can't create a thread to receive packets. Sets errno. See
\fBpthread_create(3)\fP.
.TP
.B SK_HOSTNOTFOUND
Host not found. Sets h_errno. See \fBgethostbyname(3)\fP.
.TP
.B SK_REAPER_FAIL
Can't create a thread to reap spent threads. Sets errno. See
\fBpthread_create(3)\fP.
.TP
.B SK_WORKER_FAIL
Can't create worker thread. Sets errno. See \fBpthread_create(3)\fP.
.TP
.B SK_UNTERM_HOSPEC
Community in hostspec doesn't have ending parenthesis.
.TP
.B SK_OCTET_OVERFLOW
One of the octets in hostspec is greater than 255.
.TP
.B SK_BAD_NETMASK
Subnet mask wasn't in a understood form.
.TP
.B SK_NETMASK_OVERFLOW
Number of bits in subnet mask is too large.
.TP
.B SK_DIS_NETMASK
Subnet mask had discontinious bits.
.SH "SEE ALSO"
sk_strerror(3), sk_snmpsessions_done(3), sk_new_sfiller(3), sk_new_snmptable(3)