NAME

Intro, intro - introduction to functions and libraries

DESCRIPTION

This section describes functions found in various Solaris libraries, other than those functions described in Section 2 of this manual that directly invoke UNIX system primitives. Function declarations can be obtained from the #include files indicated on each page. Pages are grouped by library and are identified by the library name (or an abbreviation of the library name) after the section number. Collections of related libraries are grouped into volumes as described below. The first volume contains pages describing the contents of each shared library and each header used by the functions, macros, and external variables described in the remaining volumes.

DEFINITIONS

A character is any bit pattern able to fit into a byte on the machine. In some international languages, however, a "character" might require more than one byte, and is represented in multi-bytes.

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

MULTITHREADED APPLICATIONS

Both POSIX threads and Solaris threads can be used within the same application. Their implementations are completely compatible with each other; however, only POSIX threads guarantee portability to other POSIX-conforming environments.

The libpthread(3LIB) and libthread(3LIB) libraries are implemented as filters on libc(3LIB).

When compiling a multithreaded application, the -mt option must be specified on the command line.

There is no need for a multithreaded application to link with -lthread. An application must link with -lpthread only when POSIX semantics for fork(2) are desired. When an application is linked with -lpthread, a call to fork() assumes the behavior fork1(2) rather than the default behavior that forks all threads.

When compiling a POSIX-conforming application, either the _POSIX_C_SOURCE or _POSIX_PTHREAD_SEMANTICS option must be specified on the command line. For POSIX.1c-conforming applications, define the _POSIX_C_SOURCE flag to be >= 199506L:

cc -mt [ flag... ] file... -D_POSIX_C_SOURCE=199506L -lpthread

For POSIX behavior with the Solaris fork() and fork1() distinction, compile as follows:

cc -mt [ flag... ] file... -D_POSIX_PTHREAD_SEMANTICS

For Solaris threads behavior, compile as follows:

cc -mt [ flag... ] file...

Unsafe interfaces should be called only from the main thread to ensure the application's safety.

MT-Safe interfaces are denoted in the ATTRIBUTES section of the functions and libraries manual pages (see attributes(7)). If a manual page does not state explicitly that an interface is MT-Safe, the user should assume that the interface is unsafe.

REALTIME APPLICATIONS

The environment variable LD_BIND_NOW must be set to a non-null value to enable early binding. Refer to the "When Relocations are Processed" chapter in Linker and Libraries Guide for additional information.

FILES

INCDIR

LIBDIR

LIBDIR/*.so

ACKNOWLEDGMENTS

Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at http://www.opengroup.org/bookstore/.

The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation.

In the following statement, the phrase ``this text'' refers to portions of the system documentation.

Portions of this text are reprinted and reproduced in electronic form in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.

This notice shall appear on any product containing this material.

SEE ALSO

ar(1), ld(1), fork(2), stdio(3C), attributes(7), standards(7)

Linker and Libraries Guide

Performance Profiling Tools

ANSI C Programmer's Guide

DIAGNOSTICS

For functions that return floating-point values, error handling varies according to compilation mode. Under the -Xt (default) option to cc, these functions return the conventional values 0, ±HUGE, or NaN when the function is undefined for the given arguments or when the value is not representable. In the -Xa and -Xc compilation modes, ±HUGE_VAL is returned instead of ±HUGE. (HUGE_VAL and HUGE are defined in math.h to be infinity and the largest-magnitude single-precision number, respectively.)

NOTES

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

The headers 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 can also be used and will report discrepancies even if the headers are not included with #include statements. Definitions for Sections 2 and 3C 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. See the lint chapter in Performance Profiling Tools

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 a 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 headers. These names are not necessarily accessible to an application program through a header, although they can 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}.