Intro, intro - introduction to functions and libraries
This section describes functions found in various Oracle Solaris libraries, other than those functions described in Section 2 of this manual that directly invoke UNIX system primitives. 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.
Function declarations can be obtained from the #include files indicated on each page. The C compilation system automatically links programs (but not shared objects) with the standard C library, libc. The C++ compilation system additionally links the appropriate standard C++ libraries. All other libraries must be explicitly linked using –l options as specified. All libraries provided by the operating system are implemented as shared objects.
This volume describes the contents of each shared library and each header used by functions, macros, and external variables described in the remaining volumes.
The libraries described in this section are implemented as shared objects.
Descriptions of shared objects can include a definition of the global symbols that define the shared objects' public interface, for example SUNW_1.1. Other interfaces can exist within the shared object, for example SUNWprivate.1.1. The public interface provides a stable, committed set of symbols for application development. The private interfaces are for internal use only, and could change at any time.
The headers described in this section are used by functions, macros, and external variables. Headers contain function prototypes, definitions of symbolic constants, common structures, preprocessor macros, and defined types. Each function described in the remaining five volumes specifies the headers that an application must include in order to use that function. In most cases only one header is required. These headers are present on an application development system; they do have to be present on the target execution system.
The functions described in this volume are the core C library functions that are basic to application development.
These functions, together with those of Section 2, constitute the standard C library, libc, which is automatically linked by the C compilation system when building a program. Specify –lc on the cc command line to link with this library when building a shared object. See libc(3LIB) for a discussion. Some functions behave differently in standard-conforming environments. This behavior is noted on the individual manual pages. See standards(7).
The libpthread and libthread libraries are filter libraries on libc used to support programs built on older versions of Solaris. See MULTITHREADED APPLICATIONS, below.
The following libraries are also now filter libraries on libc used to support programs built on older versions of Solaris, and thus no longer need to be specified while linking programs:
asynchronous I/O library
command utility library
dynamic linking library
doors library
internationalization library
network services library
POSIX.1b Realtime Extensions library
scheduling library
security attributes database library
sendfile library
sockets library
wide character library
X/Open Networking library
These functions constitute the threads debugging library, libc_db. Specify –lc_db on the cc command line to link with this library. See libc_db(3LIB).
These functions constitute the various alternative memory allocation libraries. Specify the listed link option on the cc command line to link with each library. See the ALTERNATIVE IMPLEMENTATIONS section of malloc(3C) for an overview and comparison of all of these libraries.
|
Note that libadimalloc is only usable on ADI capable processors. watchmalloc is not normally linked when building software, but may be used by setting the LD_PRELOAD environment variable when running a program.
The functions described in this volume comprise the various networking libraries.
These functions constitute the communication protocol parser utilities library, libcommputil. Specify –lcommputil on the cc command line to link with this library. See libcommputil(3LIB).
These functions constitute the data link provider interface library, libdlpi. Specify –ldlpi on the cc command line to link with this library. See libdlpi(3LIB).
These functions constitute the DNS service discovery library, libdns_sd. Specify –ldns_sd on the cc command line to link with this library. See libdns_sd(3LIB).
These functions constitute the generic security services library. Specify –lgss on the cc command line to link with this library. See libgss(3LIB).
Functions previously documented in the network service library (3NSL), have been moved to the standard C library. They are now documented in the 3C section. The libnsl library is implemented as a filter on libc(3LIB) to support objects built on older versions of Solaris. There is no need for a new application to link with this library.
These functions constitute the Domain Name System (DNS) resolver library, libresolv. Specify –lresolv on the cc command line to link with this library. See libresolv(3LIB).
These functions constitute the remote procedure call libraries, librpcsvc and librpcsoc. The latter is provided for compatibility only; new applications should not link to it. Specify –lrpcsvc or –lrpcsoc on the cc command line to link with these libraries. See librpcsvc(3LIB).
These functions constitute the Session Initiation Protocol library, libsip. Specify –lsip on the cc command line to link with this library. See libsip(3LIB).
Functions previously documented in the socket library (3SOCKET), have been moved to the standard C library. They are now documented in the 3C section. The libsocket library is implemented as a filter on libc(3LIB) to support objects built on older versions of Solaris. There is no need for a new application to link with this library.
Functions previously documented in the X/Open networking library (3XNET), have been moved to the standard C library. They are now documented in the 3C section. The libxnet library is implemented as a filter on libc(3LIB) to support objects built on older versions of Solaris. There is no need for a new application to link with this library.
The functions described in this volume comprise the libraries that provide graphics and character screen updating capabilities.
The functions constitute the following libraries:
These functions constitute the curses library, libcurses. Specify –lcurses on the cc command line to link with this library. See libcurses(3LIB).
These functions constitute the forms library, libform. Specify –lform on the cc command line to link with this library. See libform(3LIB).
These functions constitute the menus library, libmenu. Specify –lmenu on the cc command line to link with this library. See libmenu(3LIB).
These functions constitute the panels library, libpanel. Specify –lpanel on the cc command line to link with this library. See libpanel(3LIB).
These functions constitute the X/Open curses library, located in /usr/xpg4/lib/libcurses.so. This library provides a set of internationalized functions and macros for creating and modifying input and output to a terminal screen. Included in this library are functions for creating windows, highlighting text, writing to the screen, reading from user input, and moving the cursor. X/Open Curses is designed to optimize screen update activities. The X/Open Curses library conforms fully with Issue 4 of the X/Open Extended Curses specification. See libcurses(3XCURSES).
The functions described in this volume comprise the following specialized libraries:
These functions constitute the DAX (Data Analytics Accelerator) library, libdax. Specify –ldax on the cc command line to link with this library. See libdax(3LIB).
The functions described in this volume comprise the following specialized libraries:
These functions constitute the configuration administration library, libcfgadm. Specify –lcfgadm on the cc command line to link with this library. See libcfgadm(3LIB).
These functions constitute the contract management library, libcontract. Specify –lcontract on the cc command line to link with this library. See libcontract(3LIB).
These functions constitute the CPU performance counter library, libcpc, and the process context library, libpctx. Specify –lcpc or –lpctx on the cc command line to link with these libraries. See libcpc(3LIB) and libpctx(3LIB).
These functions constitute the device ID library, libdevid. Specify –ldevid on the cc command line to link with this library. See libdevid(3LIB).
These functions constitute the device information library, libdevinfo. Specify –ldevinfo on the cc command line to link with this library. See libdevinfo(3LIB).
These functions constitute the Extensible Linking Format (ELF) access library, libelf. This library provides the interface for the creation and analyses of “elf” files; executables, objects, and shared objects. Specify –lelf on the cc command line to link with this library. See libelf(3LIB).
These functions constitute the extended accounting access library, libexacct, and the project database access library, libproject. Specify –lexacct or –lproject on the cc command line to link with these libraries. See libexacct(3LIB) and libproject(3LIB).
These functions constitute the Fibre Channel over Ethernet port management library, libfcoe. Specify –lfcoe on the cc command line to link with this library. See libfcoe(3LIB).
These functions constitute the fault management events library, libfmevent. Specify –lfmevent on the cc command line to link with this library. See libfmevent(3LIB).
These functions constitute the file system type identification library, libfstyp. Specify –lfstyp on the cc command line to link with this library. See libfstyp(3LIB).
The functions described in this volume comprise the following specialized libraries:
These functions constitute the DTrace dynamic tracing software library, libdtrace. Specify –ldtrace on the cc command line to link with this library. See libdtrace(3LIB).
These functions constitute the string pattern-matching and pathname manipulation library, libgen. Specify –lgen on the cc command line to link with this library. See libgen(3LIB).
These functions constitute the common Fibre Channel HBA information library, libhbaapi. Specify –lhbaapi on the cc command line to link with this library. See libhbaapi(3LIB).
These functions constitute the iSCSI Management library, libima. Specify –lma on the cc command line to link with this library. See libima(3LIB).
These functions constitute the iSCSI Management library for COMSTAR iSCSI target ports, libiscsit. Specify –liscsit on the cc command line to link with this library. See libiscsit(3LIB).
These functions constitute the version 1 kernel statistics library, libkstat. Specify –lkstat on the cc command line to link with this library. This library has been deprecated in favor of libkstat2 and should not be used in newly written code. See libkstat(3LIB).
These functions constitute the version 2 kernel statistics library, libkstat2. Specify –lkstat2 on the cc command line to link with this library. See libkstat2(3LIB).
The functions in the libkvm library access the kernel's virtual memory. Specify –lkvm on the cc command line to link with this library. See libkvm(3LIB).
These functions constitute the layout service library, liblayout. Specify –llayout on the cc command line to link with this library. See liblayout(3LIB).
These functions constitute the locality group library, liblgrp. Specify –llgrp on the cc command line to link with this library. See liblgrp(3LIB).
These functions constitute the mathematical library, libm. Specify –lm on the cc command line to link with this library. See libm(3LIB).
These functions constitute the user mailbox management library, libmail. Specify –lmail on the cc command line to link with this library. See libmail(3LIB).
These functions constitute the multiple precision integer mathematics library, libmp. Specify –lmp on the cc command line to link with this library. See libmp(3LIB).
These functions constitute the Common Multipath Management library, libMPAPI. Specify –lMPAPI on the cc command line to link with this library. See libMPAPI(3LIB).
These functions constitute the vector mathematics library, libmvec. Specify –lmvec on the cc command line to link with this library. See libmvec(3LIB).
These functions constitute the sandbox library, libsandbox. Specify –lsandbox on the cc command line to link with this library. See libsandbox(3LIB).
The functions described in this volume comprise the following specialized libraries:
These functions constitute the name–value pair library, libnvpair. Specify –lnvpair on the cc command line to link with this library. See libnvpair(3LIB).
These functions constitute the Pluggable Authentication Module library, libpam. Specify –lpam on the cc command line to link with this library. See libpam(3LIB).
These functions constitute the PICL library, libpicl. Specify –lpicl on the cc command line to link with this library. See libpicl(3LIB) and libpicl(3PICL).
These functions constitute the PICL plug-in library, libpicltree. Specify –lpicltree on the cc command line to link with this library. See libpicltree(3LIB) and libpicltree(3PICLTREE).
These functions constitute the pool configuration manipulation library, libpool. Specify –lpool on the cc command line to link with this library. See libpool(3LIB).
These functions constitute the Process Control library, libproc. Specify –lproc on the cc command line to link with this library. See libproc(3LIB).
These functions constitute the project database access library, libproject. Specify –lproject on the cc command line to link with this library. See libproject(3LIB).
These functions constitute the reparse point library, libreparse. Specify –lreparse on the cc command line to link with this library. See libreparse(3LIB).
The functions described in this volume comprise the following specialized libraries:
These functions constitute the service configuration facility library, libscf. Specify –lscf on the cc command line to link with this library. See libscf(3LIB).
These functions constitute the file access control library, libsec. Specify –lsec on the cc command line to link with this library. See libsec(3LIB).
These functions constitute the SRP Target Management library, libsrpt. Specify –lsrpt on the cc command line to link with this library. See libsrpt(3LIB).
These functions constitute the Statistics Store library, libsstore. Specify –lsstore on the cc command line to link with this library. See libsstore(3LIB).
These functions constitute the SCSI Target Mode Framework library, libstmf. Specify –lstmf on the cc command line to link with this library. See libstmf(3LIB).
These functions constitute the Sun legacy mathematical library, libsunmath. Specify –lsunmath on the cc command line to link with this library. For more information, see the libsunmath(3LIB) man page.
These functions constitute the system event library, libsysevent. Specify –lsysevent on the cc command line to link with this library. See libsysevent(3LIB).
These functions constitute the system object database library, libsysobj. Specify –lsysobj on the cc command line to link with this library. See libsysobj(3LIB).
These functions constitute the interactive command-line input library, libtecla. Specify –ltecla on the cc command line to link with this library. See libtecla(3LIB).
These functions constitute the Trusted Extensions library, libtsol, and the Trusted Extensions network library, libtsnet. Specify –ltsol or –ltsnet on the cc command line to link with these libraries. See libtsol(3LIB) and libtsnet(3LIB).
These functions constitute the universally unique identifier library, libuuid. Specify –luuid on the cc command line to link with this library. See libuuid(3LIB).
These functions constitute the volume management library, libvolmgt. Specify –lvolmgt on the cc command line to link with this library. See libvolmgt(3LIB).
These functions constitute the zones statistics library, libzonestat. Specify –lzonestat on the cc command line to link with this library. See libzonestat(3LIB).
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 as a multibyte character.
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 <stddef.h>. Types of the form size_t are defined in the appropriate headers.
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. See threads(7).
The libpthread(3LIB) and libthread(3LIB) libraries are implemented as filters on libc(3LIB) to support objects built on older versions of Solaris. There is no need for a multithreaded application to link with these libraries.
In the default compilation environment, when neither _POSIX_C_SOURCE nor _XOPEN_SOURCE is defined, all functions as specified by the latest POSIX standard are visible to code being compiled, along with all other functions and names provided by Solaris. For Oracle Solaris 11.4, this corresponds to The Open Group, Single UNIX Specification, Version 4, December 2010 (IEEE Std 1003.1-2008, aka XPG7, UNIX V7). The default compilation environment is equivalent to:
cc –D_POSIX_C_SOURCE=200809L –D__EXTENSIONS__ ... or cc –D_XOPEN_SOURCE=700 –D__EXTENSIONS__ ...
Prior to Oracle Solaris 11.4, the default compilation environment made the Draft-6 POSIX.1c-1995 (POSIX Threads) versions of several interfaces visible to code being compiled, rather than the final POSIX.1c-1995 versions. To allow applications that were written to use the obsolete Draft-6 interfaces to continue to be compiled and run, the __USE_DRAFT6_PROTOTYPES__ macro must be defined:
cc –D__USE_DRAFT6_PROTOTYPES__ ...
Support for the Draft-6 interfaces is provided for source compatibility only and might not be supported in future releases. Old applications should be converted to use the standard definitions.
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.
The environment variable LD_BIND_NOW must be set to a non-null value to enable early binding. See When Relocations Are Performed in Oracle Solaris 11.4 Linkers and Libraries Guide for additional information.
usually /usr/include
usually either /lib or /usr/lib (32–bit) or either /lib/64 or /usr/lib/64 (64–bit)
shared libraries
Oracle 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 https://www.opengroup.org/
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 Oracle Solaris 11 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.
This notice shall appear on any product containing this material.
ar(1), ld(1), ld.so.1(1), fork(2), stdio(3C), stddef.h(3HEAD), attributes(7), standards(7), threads(7)
Oracle Solaris 11.4 Linkers and Libraries Guide
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.)
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.
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}.