.\" @(#)isc_initialize.3x 1.0 92/02/13 Lysator
.\" ISC - networking library
.\" Copyright (C) 1992, 1999 by Peter Eriksson and Per Cederqvist of the
.\"		       Lysator Academic Computer Association.
.\"
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program; if not, write to the Free Software
.\" Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
.\"
.TH ISC_INITIALIZE 3X "13 February 1992"  "Release 1.0" "ISC LIBRARY"
.SH NAME
isc_initialize \- create a master control structure
.SH SYNOPSIS
.nf
.ft B
#include <isc.h>
.ft
.fi
.LP
.nf
.ft B
IscMaster *isc_initialize(cfg)
IscConfig *cfg;
.ft R
.fi
.SH DESCRIPTION
This function initializes an ISC master structure to be ready
to handle sessions. It returns a pointer to a master structure
that can be used as the argument in subsequent calls to functions
that create new sessions to associate a session with a master
control structure. It is also used when closing down a master
structure or removing sessions from a master structure.
.SH ARGUMENTS
The
.I cfg
argument can either be a
.SM NULL
pointer to force a set of system defaults
or point to a structure that should contain various default
values to be used by the system. The structure is defined in
.BR <isc.h>
and includes the following members:
.br
.ne 6
.LP
.RS
.nf
.ft B
.ta +\w'IscSessionConfig\0'u+\w'session;\0'u
int version;
IscSessionConfig session;
.ft R
.fi
.DT
.RE
.LP
Here
.B version
should be assigned the current configuration structure
version number that for this version is
.SM 1004.
The
.B IscSessionConfig
structure is also defined in the same file and has the
following members:
.br
.ne 6
.LP
.RS
.nf
.ft B
.ta +\w'struct\0'u+\w'unsigned\0'u+\w'no_host2ip_lookup;\0'u
struct
{
    int msgsize;
    int queuedsize;
    int dequeuelen;
    int openretries;
    int backlog;
} max;
.ft R
.fi
.DT
.RE
.LP
Here
.B msgsize
specifies the maximum number of characters that will be
read or written to the underlying file descriptor in
any one call. (Ie, the maximum packet size.)
.LP
The
.B queuedsize
member specifies the maximum number of packets to queue before 
closing down the session. This is used both for incoming
and outgoing packets.
.LP
The
.B dequeuelen
member specifies the maximum number of packets to transmit
at any one time. This is so a session with many queued packets
wont use up all server resources.
.LP
The
.B openretries
member specifies the maximum number of retries that will be made
when binding and/or connecting a session to a service.
.LP
The
.B backlog
member specifies the maximum number of concurrent outstanding TCP/IP
connections as specified by the
.BR listen(2)
system call.
It is possible to assign these members the value
.SM -1
to get the system default value.
.SH RETURN VALUES
The returned value is a pointer to a master control structure,
or NULL if an error occurs.
.SH ERRORS
.TP 10
.SM EINVAL
.I cfg
is an invalid configuration struct
.SH SEE ALSO
.BR isc (3x)