cs_connect(3N)
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 csopts structure may be used.
Since applications rarely need this 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 csopts.
The csopts structure 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(4bnu)).
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.
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.
The
buf
field of the netbuf structure should point to a
sockaddr structure.
See sys/socket.h.
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 hostname 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 csopts structure 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(3xti),
t_rcv(3xti),
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
/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
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
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
References
cs(1Mbnu),
dials(3N),
reportscheme(1Mbnu)
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(4bnu).
The Connection Server daemon logs a message to /var/adm/log/cs.log on startup.
If it is invoked with the debug option (-d),
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:
-
the port monitor
-
the Identification and Authentication Facility (IAF)
-
ID Mapping
-
Name-to-Address Mapping
Examples
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 */
. . .
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004