intro(3) SDK R4.11 intro(3)
NAME
intro - introduction to subroutines and libraries
DESCRIPTION
This section describes functions found in various libraries supplied
with the DG/UX system. Declarations for some of these functions may
be obtained from #include files indicated on the appropriate pages.
The man pages are grouped by using various suffixes after the number
3. They are sorted together in the manual.
(3C) These functions make up the "general" C functions, many of which
are part of the ANSI C language definition. The others have
traditionally been part of libc on AT&T Unix-based systems.
(3E) These functions constitute the ELF library, libelf.
(3G) These are general C functions found in libgen.
(3K) These are kernel programming routines.
(3M) These functions constitute the math library, libm. For more
details see the intro(3M).
(3N) These functions constitute the Internet Network library, Network
Services library and Transport Layer Interface library.
(3R) RPC (Remote Procedure Call) related functions.
(3S) These functions constitute the standard I/O package (see
stdio(3S)). Declarations for them may be obtained from the
#include file <stdio.h>. The functions themselves live in libc.
(3T) POSIX threads implementation. Obtained with -lthread.
(3W) Multinational Language Set (MNLS) functions - libw.
(3X) Various specialized libraries. The library names in which these
functions are found are given on the appropriate pages.
Linking libraries in the proper order
When you are linking or compiling, make sure you include only the
libraries you need and that they are in the correct order. Including
extraneous libraries or listing libraries in the wrong order can
cause undesirable results that may become apparent only later. If
library a depends on library b, library a needs to precede library b
on the command line.
IMPORTANT: Do not add -lc to the cc or gcc command line. The cc and
gcc commands place libc on the command line for you. ld, however,
does not; therefore you must add -lc. It should be the last library
on the command line.
* libthread depends on libc. If you use libthread, place it on the
command line immediately before libc (and if you also use other
libraries, make sure that you single-thread your own calls to
them).
Do not place libthread on your cc command line unless you actually
create and use threads. Linking with libthread causes the libc
functions to use extra overhead to create per-thread data and
lock/unlock global data, FILE structures, and so on. Adding
libthread may also force you to re-engineer any signal handlers in
your application (see CAUTION below). You do not want to incur this
extra overhead unless you actually create threads. The format for
the gcc command is as follows:
gcc -o output-file input-file ... -lthread
* libnsl needs libc. If you use libnsl functions, place libnsl before
libc on the command line, and if you also use libthread, place
libnsl before libthread as well. The format for the gcc command is
as follows:
gcc -o output-file input-file ... -lnsl [ -lthread ]
* libsocket needs libnsl and libc. Place it immediately before libnsl
on the command line. The format for the gcc command is as follows:
gcc -o output-file input-file ... -lsocket -lnsl [ -lthread ]
* libresolv and libtrust have no dependencies between them, but they
both need libsocket. If you need one or both, simply place them
before libsocket. The format for the gcc command is as follows:
gcc -o output-file input-file ... -lresolv -ltrust -lsocket -lnsl [
-lthread ]
* libgen needs libc. Some X libraries need libgen for the regular
expression functions regcmp and regex. libgen should precede the
libraries already mentioned. The format for the gcc command is as
follows:
gcc -o output-file input-file ... Xlibraries -lgen [ -lresolv ...
-lthread ]
WARNING: Linking static and shared system libraries together into
one executable is not supported for those system libraries which
have both a shared and static version. For example:
gcc -o output-file input-file ... -Bstatic -lsocket -Bshared -lnsl
is not supported since there is both a libsocket.a and
libsocket.so.
The default -X behavior in libc
When using cc to create an executable, the default behavior for the
-X switch is -Xa (see cc(1)). cc accomplishes this by adding the
values-Xa.o file to the link line for you. When using ld to create
an executable, if you do not provide one of either values-Xa.o,
values-Xc.o, or values-Xt.o on the link line, then the libc default
in an ELF environment will be as if the executable were linked with
values-Xt.o. The libc default in a COFF environment will be as if the
executable were linked with values-Xa.o.
Software Development Environments (SDE)
The DG/UX system provides a number of Software Development
Environments, or SDEs. An SDE represents a target binary or object
interface. It is made up of a set of libraries (object and binary
interfaces) and header files (constants, data structures, types) that
may be used together to create applications that adhere to a
particular binary or object interface standard.
See sde(5) and sde-target(1) for how to select SDEs. The function
groupings described above may not be available in all the SDEs. Some
functions even appear in different libraries from one SDE to another.
88K Platform
The COFF SDEs are not available on DG/UX for the Intel platform.
The COFF SDEs provide the set of interfaces specified by the m88k
BCS/OCS standards. In the ELF environments, these interfaces may not
appear in the same libraries specified by the m88k OCS. This is due
to restructuring by AT&T in System V Release 4.
A few functions are located in different libraries in the ELF
environments than in the COFF environments. The regex and regcmp
functions are available in libPW in the COFF environments, and in
libgen in the ELF environments. The nlist function is available in
libc in the COFF environments, and in libelf in the ELF environments.
Under the COFF environments, the default floating-point environment
enables the divide by zero, floating-point overflow, and invalid
operation exceptions. These exceptions would be disabled if
<ieeefp.h> is included. Under the ELF environment, the default
floating-point environment does not enable any of the exceptions,
except invalid operation exceptions for attempted operations on IEEE
Signaling NaNs (not-a-number).
Many of the internationalization features, such as message catalog
facilities (see gettxt(3C)) that are available in the ELF environment
are absent from the COFF environments. Other internationalization
features, such as strcoll(3C), are present, but offer only C locale
behavior.
Threads
When programming with threads, reentrancy of library functions
becomes important. See reentrant(3) and cancellation(3), as well as
individual man pages, for information on using library functions in
threaded code. See threads(5) for more information on threads.
Some libc functions are not reentrant but do have reentrant
counterparts. The reentrant counterparts must be used if threads are
active in the process. These functions have an "_r" suffix on their
name. The man pages for the non-reentrant functions list their
reentrant counterparts and their behavior.
X/Open XPG4
In order to preserve existing functionality and to be XPG4 compliant,
strftime, cftime, ascftime, and system were modified to have both the
XPG4 and previous functionality. If you want the XPG4 behavior, link
in libxpg4. Linking in this new library will cause these functions to
exhibit the XPG4 behavior. See the individual man pages for more
details.
Definitions
character Any bit pattern able to fit into a byte on the
machine.
null character A character with value 0, represented in the C
language as '\0'.
character array A sequence of characters.
null-terminated character array
A sequence of characters, the last of which is the
null character.
string is a designation for a null-terminated character
array.
null string A character array containing only the null character.
NULL pointer The value that is obtained by casting 0 into a
pointer. The C language guarantees that this value
will not match that of any legitimate pointer, so
many functions that return pointers return it to
indicate an error.
NULL Defined as 0 in <stdio.h>; the user may include an
appropriate definition if not using <stdio.h>.
FILES
/usr/sde/*/usr/lib/*
Any SDE-specific components linked via elinks in /usr
/usr/lib/dguxlibraryfunctions
List of functionname libraryname pairs useful for
locating which library a given function is in.
SEE ALSO
ar(1), cc(1), ld(1), lint(1), nm(1), sde-target(1), reentrant(3),
cancellation(3), threads(5), intro(2), intro(3M), intro(3N),
stdio(3S), math(5).
CAUTION
Replacing library symbols
Many of the functions in the libraries call and/or refer to other
functions and external variables described in this section and in
Chapter 2 (System Calls). If a program inadvertently defines a
function or external variable with the same name, the presumed
library version of the function or external variable may not be
loaded. Replacing library symbols in this manner is generally
discouraged because the replacement function may not have all the
functionality required by the libraries.
Using signals in threaded applications
According to IEEE Std 1003.1-1990 (POSIX), signal catching functions
should only access system facilities which are considered reentrant
with respect to signals. POSIX contains a list of those functions.
These are the only functions that may be used in signal handlers
safely. In a threaded application, using any other functions may
cause deadlocks.
Licensed material--property of copyright holder(s)