1 '\" te
2 .\" Copyright 2017 Peter Tribble
3 .\" Copyright 2015 Joyent, Inc.
4 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
5 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
6 .\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with
7 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
8 .TH INTRO 3 "Nov 26, 2017"
9 .SH NAME
10 Intro, intro \- introduction to functions and libraries
11 .SH DESCRIPTION
12 .LP
13 This section describes functions found in various Solaris libraries, other than
14 those functions described in Section 2 of this manual that directly invoke UNIX
15 system primitives. Function declarations can be obtained from the
16 \fB#include\fR files indicated on each page. Pages are grouped by library and
17 are identified by the library name (or an abbreviation of the library name)
18 after the section number. Collections of related libraries are grouped into
19 volumes as described below. The first volume contains pages describing the
20 contents of each shared library and each header used by the functions, macros,
21 and external variables described in the remaining volumes.
22 .SS "Library Interfaces and Headers"
23 .LP
24 This volume describes the contents of each shared library and each header used
25 by functions, macros, and external variables described in the remaining
26 volumes.
27 .sp
28 .ne 2
29 .na
30 \fB(3LIB)\fR
31 .ad
32 .sp .6
33 .RS 4n
34 The libraries described in this section are implemented as shared objects.
35 .sp
36 Descriptions of shared objects can include a definition of the global symbols
37 that define the shared objects' public interface, for example \fBSUNW_1.1\fR.
38 Other interfaces can exist within the shared object, for example
39 \fBSUNWprivate.1.1\fR. The public interface provides a stable, committed set of
40 symbols for application development. The private interfaces are for internal
41 use only, and could change at any time.
42 .RE
43
44 .sp
45 .ne 2
46 .na
47 \fB(3HEAD)\fR
48 .ad
49 .sp .6
50 .RS 4n
51 The headers described in this section are used by functions, macros, and
52 external variables. Headers contain function prototypes, definitions of
53 symbolic constants, common structures, preprocessor macros, and defined types.
54 Each function described in the remaining five volumes specifies the headers
55 that an application must include in order to use that function. In most cases
56 only one header is required. These headers are present on an application
57 development system; they do have to be present on the target execution system.
58 .RE
59
60 .SS "Basic Library Functions"
61 .LP
62 The functions described in this volume are the core C library functions that
63 are basic to application development.
64 .sp
65 .ne 2
66 .na
67 \fB(3C)\fR
68 .ad
69 .sp .6
70 .RS 4n
71 These functions, together with those of Section 2, constitute the standard C
72 library, \fBlibc\fR, which is automatically linked by the C compilation system.
73 The standard C library is implemented as a shared object, \fBlibc.so\fR. See
74 \fBlibc\fR(3LIB) and the "C Compilation System" chapter of the \fIANSI C
75 Programmer's Guide\fR for a discussion. Some functions behave differently in
76 standard-conforming environments. This behavior is noted on the individual
77 manual pages. See \fBstandards\fR(5).
78 .sp
79 The \fBlibpthread\fR and \fBlibthread\fR libraries are filter libraries on
80 \fBlibc\fR that are used for building multithreaded applications:
81 \fBlibpthread\fR implements the POSIX (see \fBstandards\fR(5)) threads
100 .ne 2
101 .na
102 \fB(3MALLOC)\fR
103 .ad
104 .sp .6
105 .RS 4n
106 These functions constitute the various memory allocation libraries:
107 \fBlibmalloc\fR, \fBlibbsdmalloc\fR, \fBlibmapmalloc\fR, \fBlibmtmalloc\fR, and
108 \fBlibumem\fR. Each of these libraries is implemented as a shared object
109 (\fBlibmalloc.so\fR, \fBlibbsdmalloc.so\fR, \fBlibmapmalloc.so\fR,
110 \fBlibmtmalloc.so\fR, and \fBlibumem.so\fR). These libraries are not
111 automatically linked by the C compilation system. Specify \fB-lmalloc\fR,
112 \fB-lbsdmalloc\fR, \fB-lmapmalloc\fR, \fB-lmtmalloc\fR, and \fB-lumem\fR to
113 link with, respectively, \fBlibmalloc\fR, \fBlibbsdmalloc\fR,
114 \fBlibmapmalloc\fR, \fBlibmtmalloc\fR, and \fBlibumem\fR. See
115 \fBlibmalloc\fR(3LIB), \fBlibbsdmalloc\fR(3LIB), \fBlibmapmalloc\fR(3LIB),
116 \fBlibmtmalloc\fR(3LIB), and \fBlibumem\fR(3LIB).
117 .RE
118
119 .SS "Networking Library Functions"
120 .LP
121 The functions described in this volume comprise the various networking
122 libraries.
123 .sp
124 .ne 2
125 .na
126 \fB(3COMMPUTIL)\fR
127 .ad
128 .sp .6
129 .RS 4n
130 These functions constitute the communication protocol parser utilities library,
131 \fBlibcommputil\fR. This library is implemented as a shared object,
132 \fBlibcommputil.so\fR, but it is not automatically linked by the C compilation
133 system. Specify \fB-lcommputil\fR on the \fBcc\fR command line to link with
134 this library. See \fBlibcommputil\fR(3LIB).
135 .RE
136
137 .sp
138 .ne 2
139 .na
140 \fB(3DLPI)\fR
296 .sp .6
297 .RS 4n
298 These functions constitute X/Open networking interfaces which comply with the
299 X/Open CAE Specification, Networking Services, Issue 4 (September, 1994). This
300 library is implemented as a shared object, \fBlibxnet.so\fR, but is not
301 automatically linked by the C compilation system. Specify \fB-lxnet\fR on the
302 \fBcc\fR command line to link with this library. See \fBlibxnet\fR(3LIB) and
303 \fBstandards\fR(5) for compilation information.
304 .RE
305
306 .sp
307 .LP
308 Under all circumstances, the use of the Sockets API is recommended over the XTI
309 and TLI APIs. If portability to other XPGV4v2 (see \fBstandards\fR(5)) systems
310 is a requirement, the application must use the \fBlibxnet\fR interfaces. If
311 portability is not required, the sockets interfaces in \fBlibsocket\fR and
312 \fBlibnsl\fR are recommended over those in \fBlibxnet\fR. Between the XTI and
313 TLI APIs, the \fBXTI\fR interfaces (available with \fBlibxnet\fR) are
314 recommended over the \fBTLI\fR interfaces (available with \fBlibnsl\fR).
315 .SS "Curses Library Functions"
316 .LP
317 The functions described in this volume comprise the libraries that provide
318 graphics and character screen updating capabilities.
319 .sp
320 .ne 2
321 .na
322 \fB(3CURSES)\fR
323 .ad
324 .sp .6
325 .RS 4n
326 The functions constitute the following libraries:
327 .sp
328 .ne 2
329 .na
330 \fB\fBlibcurses\fR\fR
331 .ad
332 .sp .6
333 .RS 4n
334 These functions constitute the curses library, \fBlibcurses\fR. This library is
335 implemented as a shared object, \fBlibcurses.so\fR, but is not automatically
336 linked by the C compilation system. Specify \fB-lcurses\fR on the \fBcc\fR
379 .RE
380
381 .sp
382 .ne 2
383 .na
384 \fB(3XCURSES)\fR
385 .ad
386 .sp .6
387 .RS 4n
388 These functions constitute the X/Open curses library, located in
389 \fB/usr/xpg4/lib/libcurses.so\fR. This library provides a set of
390 internationalized functions and macros for creating and modifying input and
391 output to a terminal screen. Included in this library are functions for
392 creating windows, highlighting text, writing to the screen, reading from user
393 input, and moving the cursor. X/Open Curses is designed to optimize screen
394 update activities. The X/Open Curses library conforms fully with Issue 4 of the
395 X/Open Extended Curses specification. See \fBlibcurses\fR(3XCURSES).
396 .RE
397
398 .SS "Extended Library Functions"
399 .LP
400 The functions described in this volume comprise the following specialized
401 libraries:
402 .sp
403 .ne 2
404 .na
405 \fB(3BSM)\fR
406 .ad
407 .sp .6
408 .RS 4n
409 These functions constitute the auditing library, \fBlibbsm\fR. This
410 library is implemented as a shared object, \fBlibbsm.so\fR, but is not
411 automatically linked by the C compilation system. Specify \fB-lbsm\fR on the
412 \fBcc\fR command line to link with this library. See \fBlibbsm\fR(3LIB).
413 .RE
414
415 .sp
416 .ne 2
417 .na
418 \fB(3CFGADM)\fR
419 .ad
813 .sp
814 .ne 2
815 .na
816 \fB(3RSM)\fR
817 .ad
818 .sp .6
819 .RS 4n
820 These functions constitute the remote shared memory library, \fBlibrsm\fR. This
821 library is implemented as a shared object, \fBlibrsm.so\fR, but is not
822 automatically linked by the C compilation system. Specify \fB-lrsm\fR on the
823 \fBcc\fR command line to link with this library. See \fBlibrsm\fR(3LIB).
824 .RE
825
826 .sp
827 .ne 2
828 .na
829 \fB(3SCF)\fR
830 .ad
831 .sp .6
832 .RS 4n
833 These functions constitute the object-caching memory allocation library,
834 \fBlibscf\fR. This library is implemented as a shared object, \fBlibscf.so\fR,
835 but is not automatically linked by the C compilation system. Specify
836 \fB-lscf\fR on the \fBcc\fR command line to link with this library. See
837 \fBlibscf\fR(3LIB).
838 .RE
839
840 .sp
841 .ne 2
842 .na
843 \fB(3SEC)\fR
844 .ad
845 .sp .6
846 .RS 4n
847 These functions constitute the file access control library, \fBlibsec\fR. This
848 library is implemented as a shared object, \fBlibsec.so\fR, but is not
849 automatically linked by the C compilation system. Specify \fB-lsec\fR on the
850 \fBcc\fR command line to link with this library. See \fBlibsec\fR(3LIB).
851 .RE
852
853 .sp
948 \fBlibuuid\fR. This library is implemented as a shared object,
949 \fBlibuuid.so\fR, but is not automatically linked by the C compilation system.
950 Specify \fB-luuid\fR on the \fBcc\fR command line to link with this library.
951 See \fBlibuuid\fR(3LIB).
952 .RE
953
954 .sp
955 .ne 2
956 .na
957 \fB(3VOLMGT)\fR
958 .ad
959 .sp .6
960 .RS 4n
961 These functions constitute the volume management library, \fBlibvolmgt\fR. This
962 library is implemented as a shared object, \fBlibvolmgt.so\fR, but is not
963 automatically linked by the C compilation system. Specify \fB-lvolmgt\fR on the
964 \fBcc\fR command line to link with this library. See \fBlibvolmgt\fR(3LIB).
965 .RE
966
967 .SH DEFINITIONS
968 .LP
969 A character is any bit pattern able to fit into a byte on the machine. In some
970 international languages, however, a "character" might require more than one
971 byte, and is represented in multi-bytes.
972 .sp
973 .LP
974 The null character is a character with value 0, conventionally represented in
975 the C language as \fB\e\|0\fR\&. A character array is a sequence of characters.
976 A null-terminated character array (a \fIstring\fR) is a sequence of characters,
977 the last of which is the null character. The null string is a character array
978 containing only the terminating null character. A null pointer is the value
979 that is obtained by casting \fB0\fR into a pointer. C guarantees that this
980 value will not match that of any legitimate pointer, so many functions that
981 return pointers return \fINULL\fR to indicate an error. The macro \fINULL\fR is
982 defined in <\fBstdio.h\fR>. Types of the form \fBsize_t\fR are defined in the
983 appropriate headers.
984 .SH MULTITHREADED APPLICATIONS
985 .LP
986 Both POSIX threads and Solaris threads can be used within the same application.
987 Their implementations are completely compatible with each other; however, only
988 POSIX threads guarantee portability to other POSIX-conforming environments.
989 .sp
990 .LP
991 The \fBlibpthread\fR(3LIB) and \fBlibthread\fR(3LIB) libraries are implemented
992 as filters on \fBlibc\fR(3LIB).
993 .sp
994 .LP
995 When compiling a multithreaded application, the \fB-mt\fR option must be
996 specified on the command line.
997 .sp
998 .LP
999 There is no need for a multithreaded application to link with \fB-lthread\fR.
1000 An application must link with \fB-lpthread\fR only when POSIX semantics for
1001 \fBfork\fR(2) are desired. When an application is linked with \fB-lpthread\fR,
1002 a call to \fBfork()\fR assumes the behavior \fBfork1\fR(2) rather than the
1003 default behavior that forks all threads.
1004 .sp
1005 .LP
1029 .LP
1030 For Solaris threads behavior, compile as follows:
1031 .sp
1032 .in +2
1033 .nf
1034 \fBcc\fR \fB-mt\fR [ \fIflag\fR... ] \fIfile\fR...
1035 .fi
1036 .in -2
1037
1038 .sp
1039 .LP
1040 Unsafe interfaces should be called only from the main thread to ensure the
1041 application's safety.
1042 .sp
1043 .LP
1044 MT-Safe interfaces are denoted in the \fBATTRIBUTES\fR section of the functions
1045 and libraries manual pages (see \fBattributes\fR(5)). If a manual page does not
1046 state explicitly that an interface is MT-Safe, the user should assume that the
1047 interface is unsafe.
1048 .SH REALTIME APPLICATIONS
1049 .LP
1050 The environment variable \fBLD_BIND_NOW\fR must be set to a non-null value to
1051 enable early binding. Refer to the "When Relocations are Processed" chapter in
1052 \fILinker and Libraries Guide\fR for additional information.
1053 .SH FILES
1054 .ne 2
1055 .na
1056 \fB\fIINCDIR\fR\fR
1057 .ad
1058 .RS 15n
1059 usually \fB/usr/include\fR
1060 .RE
1061
1062 .sp
1063 .ne 2
1064 .na
1065 \fB\fILIBDIR\fR\fR
1066 .ad
1067 .RS 15n
1068 usually either \fB/lib\fR or \fB/usr/lib\fR (32-bit) or either \fB/lib/64\fR or
1069 \fB/usr/lib/64\fR (64-bit)
1070 .RE
1071
1072 .sp
1073 .ne 2
1074 .na
1075 \fB\fILIBDIR\fR\fB/*.so\fR\fR
1076 .ad
1077 .RS 15n
1078 shared libraries
1079 .RE
1080
1081 .SH ACKNOWLEDGMENTS
1082 .LP
1083 Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to
1084 reproduce portions of its copyrighted documentation. Original documentation
1085 from The Open Group can be obtained online at
1086 http://www.opengroup.org/bookstore/\&.
1087 .sp
1088 .LP
1089 The Institute of Electrical and Electronics Engineers and The Open Group, have
1090 given us permission to reprint portions of their documentation.
1091 .sp
1092 .LP
1093 In the following statement, the phrase ``this text'' refers to portions of the
1094 system documentation.
1095 .sp
1096 .LP
1097 Portions of this text are reprinted and reproduced in electronic form in the
1098 SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for
1099 Information Technology -- Portable Operating System Interface (POSIX), The Open
1100 Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of
1101 Electrical and Electronics Engineers, Inc and The Open Group. In the event of
1102 any discrepancy between these versions and the original IEEE and The Open Group
1103 Standard, the original IEEE and The Open Group Standard is the referee
1104 document. The original Standard can be obtained online at
1105 http://www.opengroup.org/unix/online.html\&.
1106 .sp
1107 .LP
1108 This notice shall appear on any product containing this material.
1109 .SH SEE ALSO
1110 .LP
1111 \fBar\fR(1), \fBld\fR(1), \fBfork\fR(2), \fBstdio\fR(3C), \fBattributes\fR(5),
1112 \fBstandards\fR(5)
1113 .sp
1114 .LP
1115 \fILinker and Libraries Guide\fR
1116 .sp
1117 .LP
1118 \fIPerformance Profiling Tools\fR
1119 .sp
1120 .LP
1121 \fIANSI C Programmer's Guide\fR
1122 .SH DIAGNOSTICS
1123 .LP
1124 For functions that return floating-point values, error handling varies
1125 according to compilation mode. Under the \fB-Xt\fR (default) option to
1126 \fBcc\fR, these functions return the conventional values \fB0\fR,
1127 \fB\(+-HUGE\fR, or \fBNaN\fR when the function is undefined for the given
1128 arguments or when the value is not representable. In the \fB-Xa\fR and
1129 \fB-Xc\fR compilation modes, \fB\(+-HUGE_VAL\fR is returned instead of
1130 \fB\(+-HUGE\fR\&. (\fBHUGE_VAL\fR and \fBHUGE\fR are defined in \fBmath.h\fR to
1131 be infinity and the largest-magnitude single-precision number, respectively.)
1132 .SH NOTES
1133 .LP
1134 None of the functions, external variables, or macros should be redefined in the
1135 user's programs. Any other name can be redefined without affecting the behavior
1136 of other library functions, but such redefinition might conflict with a
1137 declaration in an included header.
1138 .sp
1139 .LP
1140 The headers in \fIINCDIR\fR provide function prototypes (function declarations
1141 including the types of arguments) for most of the functions listed in this
1142 manual. Function prototypes allow the compiler to check for correct usage of
1143 these functions in the user's program. The \fBlint\fR program checker can also
1144 be used and will report discrepancies even if the headers are not included with
1145 \fB#include\fR statements. Definitions for Sections 2 and 3C are checked
1146 automatically. Other definitions can be included by using the \fB-l\fR option
1147 to \fBlint\fR. (For example, \fB-lm\fR includes definitions for \fBlibm\fR.)
1148 Use of \fBlint\fR is highly recommended. See the \fBlint\fR chapter in
1149 \fIPerformance Profiling Tools\fR
1150 .sp
1151 .LP
1152 Users should carefully note the difference between STREAMS and \fIstream\fR.
1153 STREAMS is a set of kernel mechanisms that support the development of network
|
1 '\" te
2 .\" Copyright 2019 Peter Tribble
3 .\" Copyright 2015 Joyent, Inc.
4 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
5 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
6 .\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with
7 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
8 .TH INTRO 3 "Aug 19, 2019"
9 .SH NAME
10 Intro, intro \- introduction to functions and libraries
11 .SH DESCRIPTION
12 This section describes functions found in various Solaris libraries, other than
13 those functions described in Section 2 of this manual that directly invoke UNIX
14 system primitives. Function declarations can be obtained from the
15 \fB#include\fR files indicated on each page. Pages are grouped by library and
16 are identified by the library name (or an abbreviation of the library name)
17 after the section number. Collections of related libraries are grouped into
18 volumes as described below. The first volume contains pages describing the
19 contents of each shared library and each header used by the functions, macros,
20 and external variables described in the remaining volumes.
21 .SS "Library Interfaces and Headers"
22 This volume describes the contents of each shared library and each header used
23 by functions, macros, and external variables described in the remaining
24 volumes.
25 .sp
26 .ne 2
27 .na
28 \fB(3LIB)\fR
29 .ad
30 .sp .6
31 .RS 4n
32 The libraries described in this section are implemented as shared objects.
33 .sp
34 Descriptions of shared objects can include a definition of the global symbols
35 that define the shared objects' public interface, for example \fBSUNW_1.1\fR.
36 Other interfaces can exist within the shared object, for example
37 \fBSUNWprivate.1.1\fR. The public interface provides a stable, committed set of
38 symbols for application development. The private interfaces are for internal
39 use only, and could change at any time.
40 .RE
41
42 .sp
43 .ne 2
44 .na
45 \fB(3HEAD)\fR
46 .ad
47 .sp .6
48 .RS 4n
49 The headers described in this section are used by functions, macros, and
50 external variables. Headers contain function prototypes, definitions of
51 symbolic constants, common structures, preprocessor macros, and defined types.
52 Each function described in the remaining five volumes specifies the headers
53 that an application must include in order to use that function. In most cases
54 only one header is required. These headers are present on an application
55 development system; they do have to be present on the target execution system.
56 .RE
57
58 .SS "Basic Library Functions"
59 The functions described in this volume are the core C library functions that
60 are basic to application development.
61 .sp
62 .ne 2
63 .na
64 \fB(3C)\fR
65 .ad
66 .sp .6
67 .RS 4n
68 These functions, together with those of Section 2, constitute the standard C
69 library, \fBlibc\fR, which is automatically linked by the C compilation system.
70 The standard C library is implemented as a shared object, \fBlibc.so\fR. See
71 \fBlibc\fR(3LIB) and the "C Compilation System" chapter of the \fIANSI C
72 Programmer's Guide\fR for a discussion. Some functions behave differently in
73 standard-conforming environments. This behavior is noted on the individual
74 manual pages. See \fBstandards\fR(5).
75 .sp
76 The \fBlibpthread\fR and \fBlibthread\fR libraries are filter libraries on
77 \fBlibc\fR that are used for building multithreaded applications:
78 \fBlibpthread\fR implements the POSIX (see \fBstandards\fR(5)) threads
97 .ne 2
98 .na
99 \fB(3MALLOC)\fR
100 .ad
101 .sp .6
102 .RS 4n
103 These functions constitute the various memory allocation libraries:
104 \fBlibmalloc\fR, \fBlibbsdmalloc\fR, \fBlibmapmalloc\fR, \fBlibmtmalloc\fR, and
105 \fBlibumem\fR. Each of these libraries is implemented as a shared object
106 (\fBlibmalloc.so\fR, \fBlibbsdmalloc.so\fR, \fBlibmapmalloc.so\fR,
107 \fBlibmtmalloc.so\fR, and \fBlibumem.so\fR). These libraries are not
108 automatically linked by the C compilation system. Specify \fB-lmalloc\fR,
109 \fB-lbsdmalloc\fR, \fB-lmapmalloc\fR, \fB-lmtmalloc\fR, and \fB-lumem\fR to
110 link with, respectively, \fBlibmalloc\fR, \fBlibbsdmalloc\fR,
111 \fBlibmapmalloc\fR, \fBlibmtmalloc\fR, and \fBlibumem\fR. See
112 \fBlibmalloc\fR(3LIB), \fBlibbsdmalloc\fR(3LIB), \fBlibmapmalloc\fR(3LIB),
113 \fBlibmtmalloc\fR(3LIB), and \fBlibumem\fR(3LIB).
114 .RE
115
116 .SS "Networking Library Functions"
117 The functions described in this volume comprise the various networking
118 libraries.
119 .sp
120 .ne 2
121 .na
122 \fB(3COMMPUTIL)\fR
123 .ad
124 .sp .6
125 .RS 4n
126 These functions constitute the communication protocol parser utilities library,
127 \fBlibcommputil\fR. This library is implemented as a shared object,
128 \fBlibcommputil.so\fR, but it is not automatically linked by the C compilation
129 system. Specify \fB-lcommputil\fR on the \fBcc\fR command line to link with
130 this library. See \fBlibcommputil\fR(3LIB).
131 .RE
132
133 .sp
134 .ne 2
135 .na
136 \fB(3DLPI)\fR
292 .sp .6
293 .RS 4n
294 These functions constitute X/Open networking interfaces which comply with the
295 X/Open CAE Specification, Networking Services, Issue 4 (September, 1994). This
296 library is implemented as a shared object, \fBlibxnet.so\fR, but is not
297 automatically linked by the C compilation system. Specify \fB-lxnet\fR on the
298 \fBcc\fR command line to link with this library. See \fBlibxnet\fR(3LIB) and
299 \fBstandards\fR(5) for compilation information.
300 .RE
301
302 .sp
303 .LP
304 Under all circumstances, the use of the Sockets API is recommended over the XTI
305 and TLI APIs. If portability to other XPGV4v2 (see \fBstandards\fR(5)) systems
306 is a requirement, the application must use the \fBlibxnet\fR interfaces. If
307 portability is not required, the sockets interfaces in \fBlibsocket\fR and
308 \fBlibnsl\fR are recommended over those in \fBlibxnet\fR. Between the XTI and
309 TLI APIs, the \fBXTI\fR interfaces (available with \fBlibxnet\fR) are
310 recommended over the \fBTLI\fR interfaces (available with \fBlibnsl\fR).
311 .SS "Curses Library Functions"
312 The functions described in this volume comprise the libraries that provide
313 graphics and character screen updating capabilities.
314 .sp
315 .ne 2
316 .na
317 \fB(3CURSES)\fR
318 .ad
319 .sp .6
320 .RS 4n
321 The functions constitute the following libraries:
322 .sp
323 .ne 2
324 .na
325 \fB\fBlibcurses\fR\fR
326 .ad
327 .sp .6
328 .RS 4n
329 These functions constitute the curses library, \fBlibcurses\fR. This library is
330 implemented as a shared object, \fBlibcurses.so\fR, but is not automatically
331 linked by the C compilation system. Specify \fB-lcurses\fR on the \fBcc\fR
374 .RE
375
376 .sp
377 .ne 2
378 .na
379 \fB(3XCURSES)\fR
380 .ad
381 .sp .6
382 .RS 4n
383 These functions constitute the X/Open curses library, located in
384 \fB/usr/xpg4/lib/libcurses.so\fR. This library provides a set of
385 internationalized functions and macros for creating and modifying input and
386 output to a terminal screen. Included in this library are functions for
387 creating windows, highlighting text, writing to the screen, reading from user
388 input, and moving the cursor. X/Open Curses is designed to optimize screen
389 update activities. The X/Open Curses library conforms fully with Issue 4 of the
390 X/Open Extended Curses specification. See \fBlibcurses\fR(3XCURSES).
391 .RE
392
393 .SS "Extended Library Functions"
394 The functions described in this volume comprise the following specialized
395 libraries:
396 .sp
397 .ne 2
398 .na
399 \fB(3BSM)\fR
400 .ad
401 .sp .6
402 .RS 4n
403 These functions constitute the auditing library, \fBlibbsm\fR. This
404 library is implemented as a shared object, \fBlibbsm.so\fR, but is not
405 automatically linked by the C compilation system. Specify \fB-lbsm\fR on the
406 \fBcc\fR command line to link with this library. See \fBlibbsm\fR(3LIB).
407 .RE
408
409 .sp
410 .ne 2
411 .na
412 \fB(3CFGADM)\fR
413 .ad
807 .sp
808 .ne 2
809 .na
810 \fB(3RSM)\fR
811 .ad
812 .sp .6
813 .RS 4n
814 These functions constitute the remote shared memory library, \fBlibrsm\fR. This
815 library is implemented as a shared object, \fBlibrsm.so\fR, but is not
816 automatically linked by the C compilation system. Specify \fB-lrsm\fR on the
817 \fBcc\fR command line to link with this library. See \fBlibrsm\fR(3LIB).
818 .RE
819
820 .sp
821 .ne 2
822 .na
823 \fB(3SCF)\fR
824 .ad
825 .sp .6
826 .RS 4n
827 These functions constitute the service configuration facility library,
828 \fBlibscf\fR. This library is implemented as a shared object, \fBlibscf.so\fR,
829 but is not automatically linked by the C compilation system. Specify
830 \fB-lscf\fR on the \fBcc\fR command line to link with this library. See
831 \fBlibscf\fR(3LIB).
832 .RE
833
834 .sp
835 .ne 2
836 .na
837 \fB(3SEC)\fR
838 .ad
839 .sp .6
840 .RS 4n
841 These functions constitute the file access control library, \fBlibsec\fR. This
842 library is implemented as a shared object, \fBlibsec.so\fR, but is not
843 automatically linked by the C compilation system. Specify \fB-lsec\fR on the
844 \fBcc\fR command line to link with this library. See \fBlibsec\fR(3LIB).
845 .RE
846
847 .sp
942 \fBlibuuid\fR. This library is implemented as a shared object,
943 \fBlibuuid.so\fR, but is not automatically linked by the C compilation system.
944 Specify \fB-luuid\fR on the \fBcc\fR command line to link with this library.
945 See \fBlibuuid\fR(3LIB).
946 .RE
947
948 .sp
949 .ne 2
950 .na
951 \fB(3VOLMGT)\fR
952 .ad
953 .sp .6
954 .RS 4n
955 These functions constitute the volume management library, \fBlibvolmgt\fR. This
956 library is implemented as a shared object, \fBlibvolmgt.so\fR, but is not
957 automatically linked by the C compilation system. Specify \fB-lvolmgt\fR on the
958 \fBcc\fR command line to link with this library. See \fBlibvolmgt\fR(3LIB).
959 .RE
960
961 .SH DEFINITIONS
962 A character is any bit pattern able to fit into a byte on the machine. In some
963 international languages, however, a "character" might require more than one
964 byte, and is represented in multi-bytes.
965 .sp
966 .LP
967 The null character is a character with value 0, conventionally represented in
968 the C language as \fB\e\|0\fR\&. A character array is a sequence of characters.
969 A null-terminated character array (a \fIstring\fR) is a sequence of characters,
970 the last of which is the null character. The null string is a character array
971 containing only the terminating null character. A null pointer is the value
972 that is obtained by casting \fB0\fR into a pointer. C guarantees that this
973 value will not match that of any legitimate pointer, so many functions that
974 return pointers return \fINULL\fR to indicate an error. The macro \fINULL\fR is
975 defined in <\fBstdio.h\fR>. Types of the form \fBsize_t\fR are defined in the
976 appropriate headers.
977 .SH MULTITHREADED APPLICATIONS
978 Both POSIX threads and Solaris threads can be used within the same application.
979 Their implementations are completely compatible with each other; however, only
980 POSIX threads guarantee portability to other POSIX-conforming environments.
981 .sp
982 .LP
983 The \fBlibpthread\fR(3LIB) and \fBlibthread\fR(3LIB) libraries are implemented
984 as filters on \fBlibc\fR(3LIB).
985 .sp
986 .LP
987 When compiling a multithreaded application, the \fB-mt\fR option must be
988 specified on the command line.
989 .sp
990 .LP
991 There is no need for a multithreaded application to link with \fB-lthread\fR.
992 An application must link with \fB-lpthread\fR only when POSIX semantics for
993 \fBfork\fR(2) are desired. When an application is linked with \fB-lpthread\fR,
994 a call to \fBfork()\fR assumes the behavior \fBfork1\fR(2) rather than the
995 default behavior that forks all threads.
996 .sp
997 .LP
1021 .LP
1022 For Solaris threads behavior, compile as follows:
1023 .sp
1024 .in +2
1025 .nf
1026 \fBcc\fR \fB-mt\fR [ \fIflag\fR... ] \fIfile\fR...
1027 .fi
1028 .in -2
1029
1030 .sp
1031 .LP
1032 Unsafe interfaces should be called only from the main thread to ensure the
1033 application's safety.
1034 .sp
1035 .LP
1036 MT-Safe interfaces are denoted in the \fBATTRIBUTES\fR section of the functions
1037 and libraries manual pages (see \fBattributes\fR(5)). If a manual page does not
1038 state explicitly that an interface is MT-Safe, the user should assume that the
1039 interface is unsafe.
1040 .SH REALTIME APPLICATIONS
1041 The environment variable \fBLD_BIND_NOW\fR must be set to a non-null value to
1042 enable early binding. Refer to the "When Relocations are Processed" chapter in
1043 \fILinker and Libraries Guide\fR for additional information.
1044 .SH FILES
1045 .ne 2
1046 .na
1047 \fB\fIINCDIR\fR\fR
1048 .ad
1049 .RS 15n
1050 usually \fB/usr/include\fR
1051 .RE
1052
1053 .sp
1054 .ne 2
1055 .na
1056 \fB\fILIBDIR\fR\fR
1057 .ad
1058 .RS 15n
1059 usually either \fB/lib\fR or \fB/usr/lib\fR (32-bit) or either \fB/lib/64\fR or
1060 \fB/usr/lib/64\fR (64-bit)
1061 .RE
1062
1063 .sp
1064 .ne 2
1065 .na
1066 \fB\fILIBDIR\fR\fB/*.so\fR\fR
1067 .ad
1068 .RS 15n
1069 shared libraries
1070 .RE
1071
1072 .SH ACKNOWLEDGMENTS
1073 Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to
1074 reproduce portions of its copyrighted documentation. Original documentation
1075 from The Open Group can be obtained online at
1076 http://www.opengroup.org/bookstore/\&.
1077 .sp
1078 .LP
1079 The Institute of Electrical and Electronics Engineers and The Open Group, have
1080 given us permission to reprint portions of their documentation.
1081 .sp
1082 .LP
1083 In the following statement, the phrase ``this text'' refers to portions of the
1084 system documentation.
1085 .sp
1086 .LP
1087 Portions of this text are reprinted and reproduced in electronic form in the
1088 SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for
1089 Information Technology -- Portable Operating System Interface (POSIX), The Open
1090 Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of
1091 Electrical and Electronics Engineers, Inc and The Open Group. In the event of
1092 any discrepancy between these versions and the original IEEE and The Open Group
1093 Standard, the original IEEE and The Open Group Standard is the referee
1094 document. The original Standard can be obtained online at
1095 http://www.opengroup.org/unix/online.html\&.
1096 .sp
1097 .LP
1098 This notice shall appear on any product containing this material.
1099 .SH SEE ALSO
1100 \fBar\fR(1), \fBld\fR(1), \fBfork\fR(2), \fBstdio\fR(3C), \fBattributes\fR(5),
1101 \fBstandards\fR(5)
1102 .sp
1103 .LP
1104 \fILinker and Libraries Guide\fR
1105 .sp
1106 .LP
1107 \fIPerformance Profiling Tools\fR
1108 .sp
1109 .LP
1110 \fIANSI C Programmer's Guide\fR
1111 .SH DIAGNOSTICS
1112 For functions that return floating-point values, error handling varies
1113 according to compilation mode. Under the \fB-Xt\fR (default) option to
1114 \fBcc\fR, these functions return the conventional values \fB0\fR,
1115 \fB\(+-HUGE\fR, or \fBNaN\fR when the function is undefined for the given
1116 arguments or when the value is not representable. In the \fB-Xa\fR and
1117 \fB-Xc\fR compilation modes, \fB\(+-HUGE_VAL\fR is returned instead of
1118 \fB\(+-HUGE\fR\&. (\fBHUGE_VAL\fR and \fBHUGE\fR are defined in \fBmath.h\fR to
1119 be infinity and the largest-magnitude single-precision number, respectively.)
1120 .SH NOTES
1121 None of the functions, external variables, or macros should be redefined in the
1122 user's programs. Any other name can be redefined without affecting the behavior
1123 of other library functions, but such redefinition might conflict with a
1124 declaration in an included header.
1125 .sp
1126 .LP
1127 The headers in \fIINCDIR\fR provide function prototypes (function declarations
1128 including the types of arguments) for most of the functions listed in this
1129 manual. Function prototypes allow the compiler to check for correct usage of
1130 these functions in the user's program. The \fBlint\fR program checker can also
1131 be used and will report discrepancies even if the headers are not included with
1132 \fB#include\fR statements. Definitions for Sections 2 and 3C are checked
1133 automatically. Other definitions can be included by using the \fB-l\fR option
1134 to \fBlint\fR. (For example, \fB-lm\fR includes definitions for \fBlibm\fR.)
1135 Use of \fBlint\fR is highly recommended. See the \fBlint\fR chapter in
1136 \fIPerformance Profiling Tools\fR
1137 .sp
1138 .LP
1139 Users should carefully note the difference between STREAMS and \fIstream\fR.
1140 STREAMS is a set of kernel mechanisms that support the development of network
|