cs_connect(3N) cs_connect(3N)
NAME
cs_connect, cs_perror - application interface to the
Connection Server
SYNOPSIS
cc [options] file -lnsl
#include <cs.h>
int cs_connect(const char *host, char *service,
struct csopts *cs_opt, int *error);
void cs_perror(const char *string, int error);
DESCRIPTION
The library routines cs_connect and cs_perror provide an
interface that network applications use to establish an
authenticated TLI/XTI connection to a network service on host.
The Connection Server interface shields the client application
from details of connection establishment and authentication.
Since cs_connect performs authentication on behalf of the
client process, authentication is effectively automated. The
way in which cs_connect accesses authentication schemes also
allows the system administrator to use modular schemes that
are interchangeable and can be administered on a per-service
basis.
cs_connect communicates with the Connection Server daemon,
which establishes a TLI/XTI connection on behalf of the client
application and returns a file descriptor associated with the
connection. The Connection Server uses the Network Selection
mechanism to determine the transport provider needed to
connect to the specified service and uses the Name-to-Address
Mapping facility to obtain the address of the network service
over that transport.
The arguments are defined as follows:
host The name of the server machine that is supplying the
service. This name can be any string acceptable to
the Name-to-Address Mapping facility.
service The name of the service with which the application
wishes to communicate. To connect to a service via
the NLPS server use the following syntax:
listen:service tag
where service tag is the argument taken from the first
field in _pmtab on the server machine.
cs_opt To bind to a reserved port, or to make a special type
of network selection, the structure csopts may be
used. Since applications rarely need this
Copyright 1994 Novell, Inc. Page 1
cs_connect(3N) cs_connect(3N)
functionality, this argument will typically be NULL.
Network selection usually means restricting the choice
of transport providers by name (where a transport
provider name is specified in the first field of the
/etc/netconfig file). The preferred method of
selection is setting the NETPATH environment variable
to a colon-separated list of transport provider names.
To do such special types of network selection as
restricting by network semantics, use the struct
csopts.
The structure csopts is defined in the header file
/usr/include/cs.h as:
struct csopts {
struct netconfig *nc_p;
int nd_opt;
struct netbuf *nb_p;
};
The elements of this structure are as follows:
struct netconfig *nc_p
To restrict the networks which may be used in
making a connection, the user may set the
element nc_p to point to a netconfig structure.
A network will be selected which matches with
all the elements in the netconfig structure that
have been filled in by the user [see
netconfig(4)]. For example, if the user wants
to use only TCP protocol networks, then
nc_p->nc_proto should be set to tcp and all
other elements should be set to zero or NULL.
If the user does not want to restrict network
selection but does want to bind to a reserved
port, nc_p should be set to
(struct netconfig *)NULL
and the other members should be set as described
below.
int nd_opt
To bind to a reserved port, the user should set
this element to ND_SET_RESERVEDPORT. See
netdir(3N).
struct netbuf *nb_p
To bind to a reserved port on a specific
address, nd_opt should be set as described above
and nb_p should be set to point to a netbuf
structure. See netdir(3N). The buf field of
the netbuf structure should point to a sockaddr
structure. See sys/socket.h.
Copyright 1994 Novell, Inc. Page 2
cs_connect(3N) cs_connect(3N)
error An int that is declared in the application that calls
cs_connect and cs_perror. A pointer to error is
passed to cs_connect and will be set to an error
value. Calling cs_perror with the value of error will
print out an appropriate error message.
string The string that is to precede error messages.
The Connection Server establishes a connection by trying each
visible transport provider in the order listed in
/etc/netconfig. Users can choose the transport providers to
be tried and the order in which they will be tried by setting
the NETPATH environment variable to a colon-separated list of
transport provider names. (A transport provider name is
specified in the first field of the /etc/netconfig file.)
cs_connect establishes communication with the Connection
Server daemon via a named pipe and sends the host name and
service name as parameters. cs_connect also sends the value
of the NETPATH environment variable, or a NULL value if
NETPATH is not set. If the pointer to the structure csopts is
not NULL, cs_connect will send the contents of the three
member structures with the exception of the last two elements
of struct netconfig (that is, nc_lookups and nc_nlookups).
The Connection Server daemon uses the Network Selection and
Name-to-Address Mapping facilities to attempt to establish an
authenticated connection to host for service over each
available transport until a connection is established or
connection establishment fails for every transport. Transport
providers may be restricted by setting the NETPATH environment
variable to a colon-separated list of transport provider
names. See environ(5).
The Connection Server consults the /etc/iaf/serve.allow file
for the list of authentication schemes acceptable to the
client machine for service on host.
If an authenticated connection is established, the Connection
Server returns a file descriptor associated with the
connection. The application can then perform all TLI/XTI
operations-t_snd(3N), t_rcv(3N), and so on-on the file
descriptor.
cs_perror prints an error message on the standard error. The
error message is derived from indexing a value referenced by
error, which was set by cs_connect. The message is preceded
by string and a colon.
Files
/etc/cs/auth Connection Server authentication scheme file
Copyright 1994 Novell, Inc. Page 3
cs_connect(3N) cs_connect(3N)
/etc/iaf/serve.alias
database of network services and their aliases
/etc/iaf/serve.allow
database of allowable authentication schemes
and network services
/etc/inet/hosts Name-to-Address Mapping hosts file for TCP.
For compatibility, /etc/inet/hosts is linked
to /etc/hosts.
/etc/inet/services
Name-to-Address Mapping services file for TCP.
For compatibility, /etc/inet/services is
linked to /etc/services.
/etc/net/transport_name/hosts
Name-to-Address Mapping hosts file for
transport_name
/etc/net/transport_name/services
Name-to-Address Mapping services file for
transport_name
/etc/netconfig Network Selection database file
/var/adm/log/cs.debug
Connection Server debug file
/var/adm/log/cs.log
Connection Server log file
/usr/lib/locale/locale/LC_MESSAGES/uxnsu
Return Values
On success, cs_connect returns a file descriptor containing a
positive integer. On failure, cs_connect returns -1.
On failure, cs_perror may report the following errors:
CS_NO_ERROR No Error
CS_SYS_ERROR
System Error
Copyright 1994 Novell, Inc. Page 4
cs_connect(3N) cs_connect(3N)
CS_DIAL_ERROR
Dial error
CS_MALLOC No Memory
CS_AUTH Authentication scheme specified by server is not
acceptable
CS_CONNECT Connection to service failed
CS_INVOKE Error in invoking authentication scheme
CS_SCHEME Authentication scheme unsuccessful
CS_TRANSPORT
Could not obtain address of service over any
transport
CS_PIPE Could not create CS pipe
CS_FATTACH Could not mount remote stream to CS pipe
CS_CONNLD Could not push CONNLD
CS_FORK Could not fork CS child request
CS_CHDIR Could not chdir
CS_SETNETPATH
Host/service not found over available transport
CS_TOPEN TLI/XTI failure: t_open failed
CS_TBIND TLI/XTI failure: t_bind failed
CS_TCONNECT TLI/XTI failure: t_connect failed
CS_TALLOC TLI/XTI failure: t_alloc failed
CS_MAC MAC check failure or Secure Device access denied
CS_DAC DAC check failure or Secure Device access denied
CS_TIMEDOUT Connection attempt timed out
Copyright 1994 Novell, Inc. Page 5
cs_connect(3N) cs_connect(3N)
CS_NETPRIV Privileges not correct for requested network
options
CS_NETOPTION
Netdir option incorrectly set in csopts struct
CS_NOTFOUND Service not found in server's _pmtab
CS_LIDAUTH Connection not permitted by LIDAUTH.map
Example
A typical call to cs_connect is of the form:
#include <cs.h>
. . .
int error=0;
. . .
if ((fd = cs_connect("host", "service", (struct csopts *)NULL,
&error)) < 0) {
/* do error handling */
cs_perror("application specific string", error);
exit(1);
}
/* continue with normal execution */
. . .
REFERENCES
cs(1M), reportscheme(1M), dial(3N)
NOTICES
Not all values stored in the csopts structure are sent to the
Connection Server. In particular, the last two elements of
nc_p, that is, nc_lookups and nc_nlookups, are not sent. See
netconfig(4).
The Connection Server daemon logs a message to
/var/adm/log/cs.log on startup.
If it is invoked with the debug option, the Connection Server
daemon prints debug information to /var/adm/log/cs.debug.
/usr/sbin/cs -d
In order for network applications to use cs_connect, the
following network components must be correctly administered:
Copyright 1994 Novell, Inc. Page 6
cs_connect(3N) cs_connect(3N)
The port monitor
The Identification and Authentication Facility (IAF)
ID Mapping
Name-to-Address Mapping
Copyright 1994 Novell, Inc. Page 7