intro(3)


intro -- introduction to functions and libraries

Description

This section describes 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 a letter after the section number; however, all Section 3 manual pages are sorted together alphabetically, without regard to this letter.

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. Also see Programming in standard C and C++ in Programming in standard C and C++.)


(3C)
These functions, together with those of Section 2 and those marked (3S), constitute the standard C library, libc, which is automatically linked by the C compilation system. The standard C library, libc.so, is searched at compile time by default. Specify -dn on the cc command line to link with the archive version of this library, libc.a, and the archive version of all other libraries being searched.

(3curses)
This is the standard character user interface library, libcurses.a, which complies with the Single UNIX® Specification, Version 2 standard. It provides an API for character-based, terminal-independent screen management. See Intro(3curses).

(3ocurses)
This is the traditional UNIX® System V Release 4 curses library, which was the standard curses library in releases prior to UnixWare 7.0.1. It has been moved from libcurses.a to libocurses.a.

These functions provide character user interface capabilities in five libraries, all provided in archive versions. They are not linked automatically by the C compilation system. Specify -locurses on the cc command line to link with all these functions.

In addition, to link with the forms, menus, panels, and tam functions, specify -lform, -lmenu, -lpanel, or -ltam, respectively. Note that these libraries work only with the 3ocurses routines, and not with the 3curses routines. (See curses(3ocurses), forms(3ocurses), menus(3ocurses), panels(3ocurses), and tam(3ocurses)). For a discussion of each of these capabilities, see Character user interface programming in Character user interface programming.


(3S)
These functions constitute the ``standard I/O package'' (see Intro(3S)), and are part of the standard C library, as described above.

(3elf)
These functions constitute the Executable and Linking Format (ELF) access library, libelf (see Intro(3elf)). This library is not implemented as a shared object and is not automatically linked by the C compilation system. Specify -lelf on the cc command line to link with this library.

(3event)
These functions make up the event library libevent. This library is not implemented as a shared object and is not automatically linked by the C compilation system. Specify -levent on the cc command line to link with this library.

(3G)
These functions constitute the general-purpose library, libgen. This library is not implemented as a shared object and is not automatically linked by the C compilation system. Specify -lgen on the cc command line to link with this library.

(3I)
These functions constitute the Identification and Authentication Facility library, libiaf. This library is implemented as a shared object, libiaf.so, and an archive, libiaf.a. It is not automatically linked by the C compilation system. Specify -liaf on the cc command line to link with the shared object version of the library. Specify -dn -liaf on the cc command line to link with the archive version of this library and the archive version of all other libraries being searched.

(3M)
These functions constitute the math library, libm (see math(5)). This library is implemented as a shared object, libm.so, and an archive, libm.a. It is not automatically linked by the C compilation system. Specify -lm on the cc command line to link with the shared object version of the library. Specify -dn -lm on the cc command line to link with the archive version of this library and the archive version of all other libraries being searched.

libm contains the full set of double-precision routines, single-precision routines (designated by the suffix f) that give better performance with less precision and long double-precision routines (designated by the suffix l) that give better precision than the single or double-precision versions.


(3N)
The networking functions are contained in three libraries: the Network Services library, libnsl; the Sockets Interface library, libsocket; and the Internet Domain Name Server library, libresolv.

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. For the XTI functions, however, the entry points have new names, such as _xti_open. When applications are compiled on UnixWare 2.0, 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 libresolv library contains the resolver routines.

The standard networking libraries are implemented as shared objects (libnsl.so, libresolv.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 [options] file [[-lresolv] -lsocket] -lnsl [-lthread]

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


(3wide)
The functions in libw provide additional support for both multibyte and 32-bit wide characters beyond those functions in (3C). Some are provided only for compatibility. For a discussion, see ``Internationalization'' in Programming with system calls and libraries. This library is not implemented as a shared object and is not automatically linked by the C compilation system. Specify -lw on the cc command line to link with this library.

(3X)
Specialized libraries. The files in which these libraries are found are given on each Section 3X manual page.

(3bsd)
These functions are provided in the BSD Compatibility Package in three libraries: libucb (for most (3) manual pages], libdbm (see dbm(3bsd)), and libmp (see mp(3bsd)). These libraries are not implemented as shared objects. When C programs are compiled by invoking /usr/ucb/cc, libucb is automatically linked by the C compilation system. Even when /usr/ucb/cc is invoked, libdbm and libmp are not automatically linked, so specify -ldbm or -lmp on the /usr/ucb/cc command line to link with these libraries.

Files

INCDIR usually /usr/include
LIBDIR usually /usr/ccs/lib
LIBDIR/libc.so Compile-time Standard C Library
LIBDIR/libc.a Compile-time Standard C Library (archive)
/usr/lib/libc.so.1 Run-time Standard C Library
LIBDIR/libcurses.a ETI/curses Curses Library (archive)
LIBDIR/libelf.a Executable and Linking Format Library (archive)
LIBDIR/libform.a Form Library (archive)
LIBDIR/libgen.a General-Purpose Library (archive)
/usr/lib/libiaf.so Identification and Authentication Library
  (shared object)
/usr/lib/libiaf.a Identification and Authentication Library (archive)
/usr/lib/libm.so Mathematical Library (shared object)
LIBDIR/libm.a Mathematical Library (archive)
LIBDIR/libmenu.a Menu Library (archive)
/usr/lib/libnsl.so Network Services Library (shared object)
LIBDIR/libpanel.a Panel Library (archive)
/usr/lib/libresolv.so Internet Domain Name Server Library (shared object)
/usr/lib/libsocket.so Sockets Interface Library (shared object)
LIBDIR/libtam.a Tam Library (archive)
/usr/lib/libw.a Multibyte/Wide Character Conversion Library (archive)

 INCDIR                  usually /usr/include
 LIBDIR                  usually /usr/ccs/lib
 LIBDIR/libc.so          Compile-time Standard C Library
 LIBDIR/libc.a           Compile-time Standard C Library (archive)
 /usr/lib/libc.so.1      Run-time Standard C Library
 LIBDIR/libcurses.a      ETI/curses Curses Library (archive)
 LIBDIR/libelf.a         Executable and Linking Format Library (archive)
 LIBDIR/libform.a        Form Library (archive)
 LIBDIR/libgen.a         General-Purpose Library (archive)
 /usr/lib/libiaf.so      Identification and Authentication Library
                           (shared object)
 /usr/lib/libiaf.a       Identification and Authentication Library (archive)
 /usr/lib/libm.so        Mathematical Library (shared object)
 LIBDIR/libm.a           Mathematical Library (archive)
 LIBDIR/libmenu.a        Menu Library (archive)
 /usr/lib/libnsl.so      Network Services Library (shared object)
 LIBDIR/libpanel.a       Panel Library (archive)
 /usr/lib/libresolv.so   Internet Domain Name Server Library (shared object)
 /usr/lib/libsocket.so   Sockets Interface Library (shared object)
 LIBDIR/libtam.a         Tam Library (archive)
 /usr/lib/libw.a         Multibyte/Wide Character Conversion Library (archive)

Return values

For functions that return a floating-point value, if an error occurs, the value of errno will be one of the values represented by the manifest constants EDOM or ERANGE (defined in math.h). EDOM typically indicates a domain error: one of the input values was not in the domain of the function. ERANGE typically indicates a range error: the calculated result was either too big or too small to be represented by the data type returned by the function.

Functions that result in a range error typically return zero for underflow or a value that will compare equal to ±HUGE_VAL for overflow. HUGE_VAL is defined in math.h. On systems that support IEEE infinity, HUGE_VAL is infinity.

If the system supports IEEE NaN (not-a-number), functions that result in a domain error typically return NaN. Such functions may also raise one of the IEEE floating-point exceptions. On systems that do not support IEEE NaN, functions that result in a domain error typically return zero.

The error behavior for programs compiled with the -Xt (transitional) compilation mode is different (see cc(1)). In that case, these functions typically return zero instead of IEEE NaN for domain errors and a value that will compare equal to ±HUGE instead of ±HUGE_VAL for overflows. HUGE is defined in math.h.

Definitions

A character (except a multibyte character; see mbchar(3C)) is any bit pattern able to fit into a byte on the machine. The null character is a character with value 0, conventionally represented in the C language as \0. A character array is a sequence of characters. A null-terminated character array (a ``string'') is a sequence of characters, the last of which is the null character. The null string is a character array containing only the terminating null character. A NULL pointer is the value that is obtained by casting 0 into a pointer. C guarantees that this value will not match that of any legitimate pointer, so many functions that return pointers return NULL to indicate an error. The macro NULL is defined in stdio.h. Types of the form size_t are defined in the appropriate header files.

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.

References

ar(1), cc(1), curses(3ocurses), dbm(3bsd), forms(3ocurses), Intro(2), Intro(3curses), Intro(3elf), Intro(3S), ld(1), lint(1), math(5), mbchar(3C), menus(3ocurses), mp(3bsd), nm(1), panels(3ocurses), tam(3ocurses)

Programming in standard C and C++ in Programming in standard C and C++

Programming with system calls and libraries in Programming with system calls and libraries

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 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}.

Applications should restrict their use of the standard I/O package (see Intro(3S)) to the interfaces documented on the Section 3S manual pages. They should not depend on individual members of the internal structures found in stdio.h.


© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004