Intro(3N)

Intro -- introduction to networking functions and libraries

Description

This manual page describes networking functions found in various libraries, other than those functions that directly invoke UNIX^® system primitives, which are described in Section 2 manual pages. Function declarations can be obtained from the #include files indicated on each page. Certain major collections of functions are identified by letters after the section number.

Some libraries are available in both a shared object version and an archive version. By default, C programs will be linked with the shared object version of the standard C library (functions in Sections 2, 3C, and 3S). Other libraries can be searched by using the -l option on your cc command line. If a shared object version of the specified library exists, it will be searched. To force your executable to be linked with the archive version of all libraries being searched, specify the -dn option on the cc command line. (See cc(1) for other overrides.)

The networking functions are contained in the Sockets Interface library, libsocket, and the Network Services library, libnsl.

WARNING: The DNS resolver library, libresolv, contains the resolver routines described on resolver(3N). Do not link this library explicitly unless you call routines within it to force DNS to be used for host lookup.

The following functions constitute the libnsl library:

cr1: cr1 authentication library
cs: Connection Server library interface
des: Data Encryption Standards library
netdir: Network Directory functions. This contains look-up functions and the access point to network directory libraries for various network transports.
netselect: Network Selection routines. These functions manipulate the /etc/netconfig file and return entries.
nsl: UnixWare^® Transport Interface. These functions support both the older TLI semantics and the newer semantics of the X/OPEN Transport Interface (XTI). The library entry points have their traditional names for the TLI functions, such as t_open(3xti). For the XTI functions, however, the entry points have new names, such as _xti_open. When applications are compiled, the XTI function names are translated to the XTI entry points by macros in the include file <xti.h>.
rexec: REXEC library interface
rpc: User-level Remote Procedure Call library
yp: Network Information Service functions

The libsocket library has two components: inet, containing the Internet library routines, and socket, containing the Socket Interface routines.

The standard networking libraries are implemented as shared objects (libnsl.so and libsocket.so). They are not automatically linked by the C compilation system. To link with these libraries, specify the cc command line:

cc [-Kthread] [options] file [-lsocket] -lnsl

The specified order of libraries on the cc line must be used to insure correct linking and initialization of the libraries.

Definition of the netbuf structure

In the Network Services library, netbuf is a structure used in various XTI functions to send and receive data and information. netbuf is defined in sys/xti.h as follows:

   unsigned int maxlen;  /* The physical size of the buffer */
   unsigned int len; /* The number of bytes in the buffer */
   char *buf;  /* Points to user input and/or output buffer */

If netbuf is used to provide information to an XTI function, the caller must set the value of len. maxlen generally has significance only when buf is used to receive output from the XTI function. In this case, the caller uses maxlen to specify the maximum value of len that can be set by the function. If maxlen is not large enough to hold the returned information, a TBUFOVFLW error will generally result. However, certain functions may return part of the data and not generate an error.

Files

/usr/lib/libnsl.so: Network Services Library (shared object)
/usr/lib/libsocket.so: Sockets Interface Library (shared object)

References

ar(1), cc(1), intro(2), ld(1), lint(1), nm(1)

Notices

None of the functions, external variables, or macros should be redefined in the user's programs. Any other name may be redefined without affecting the behavior of other library functions, but such redefinition may conflict with a declaration in an included header file.

The header files in INCDIR provide function prototypes (function declarations including the types of arguments) for most of the functions listed in this manual. Function prototypes allow the compiler to check for correct usage of these functions in the user's program. The lint program checker may also be used and will report discrepancies even if the header files are not included with #include statements. Definitions for Sections 2, 3C, and 3S are checked automatically. Other definitions can be included by using the -l option to lint. (For example, -lm includes definitions for libm.) Use of lint is highly recommended.

Users should carefully note the difference between STREAMS (TM) and ``stream''. STREAMS is a set of kernel mechanisms that support the development of network services and data communication drivers. It is composed of utility routines, kernel facilities, and a set of data structures. A ``stream'' is a file with its associated buffering. It is declared to be a pointer to an object of type FILE defined in stdio.h.

In detailed definitions of components, it is sometimes necessary to refer to symbolic names that are implementation-specific, but which are not necessarily expected to be accessible to an application program. Many of these symbolic names describe boundary conditions and system limits.

In this section, for readability, these implementation-specific values are given symbolic names. These names always appear enclosed in curly brackets to distinguish them from symbolic names of other implementation-specific constants that are accessible to application programs by header files. These names are not necessarily accessible to an application program through a header file, although they may be defined in the documentation for a particular system.

In general, a portable application program should not refer to these symbolic names in its code. For example, an application program would not be expected to test the length of an argument list given to a routine to determine if it was greater than ARG_MAX.

Standards compliance

The following routines are conformant with X/Open CAE Specification, Networking Services, Issue 4, 1994 (UNIX95):
endhostent(3N), endnetent(3N), endprotoent(3N), endservent(3N), gethostbyaddr(3N), gethostbyname(3N), getnetbyaddr(3N), getprotobynumber(3N), getservbyport(3N), htonl(3N), inet_addr(3N), ntohl(3N), sethostent(3N), setnetent(3N), setprotoent(3N), setservent(3N).

The remaining routines in this section are not part of any currently supported standard.