Chapter 1 1 Introduction 2 1.1 Scope | 3 IEEE Std. 1003.1-200x defines a standard operating system interface and environment, including | 4 a command interpreter (or ``shell''), and common utility programs to support applications | 5 portability at the source code level. It is intended to be used by both applications developers | 6 and system implementors. | 7 IEEE Std. 1003.1-200x comprises three major components (each in an associated volume): | 8 1. General terms, concepts, and interfaces common to all volumes of IEEE Std. 1003.1-200x, | 9 including utility conventions and C language header definitions, are included in the Base | 10 Definitions volume of IEEE Std. 1003.1-200x. | 11 2. Definitions for system service functions and subroutines, language-specific system | 12 services for the C programming language, function issues, including portability, error | 13 handling, and error recovery, are included in the System Interfaces volume of | 14 IEEE Std. 1003.1-200x. | 15 3. Definitions for a standard source code-level interface to command interpretation services | 16 (a ``shell'') and common utility programs for application programs are included in the | 17 Shell and Utilities volume of IEEE Std. 1003.1-200x. | 18 The following areas are outside of the scope of IEEE Std. 1003.1-200x: | 19 * Graphics interfaces | 20 * Database management system interfaces | 21 * Record I/O considerations | 22 * Object or binary code portability | 23 * System configuration and resource availability | 24 IEEE Std. 1003.1-200x describes the external characteristics and facilities that are of importance | 25 to applications developers, rather than the internal construction techniques employed to achieve | 26 these capabilities. Special emphasis is placed on those functions and facilities that are needed in | 27 a wide variety of commercial applications. | 28 The facilities provided in IEEE Std. 1003.1-200x are drawn from the following base documents: | 29 * IEEE Std. 1003.1-1996 (POSIX-1) (incorporating IEEE Stds. 1003.1-1990, 1003.1b-1993, | 30 1003.1c-1995, and 1003.1i-1995) | 31 * The following amendments to the POSIX.1-1990 standard: | 32 - IEEE P1003.1a draft standard (Additional System Services) | 33 - IEEE Std. 1003.1d-1999 (Additional Realtime Extensions) | 34 - IEEE Std. 1003.1g-2000 (Protocol-Independent Interfaces (PII)) | 35 - IEEE Std. 1003.1j-2000 (Advanced Realtime Extensions) | 36 - IEEE Std. 1003.1q-2000 (Tracing) | Base Definitions, Issue 6 1 Scope Introduction 37 * IEEE Std. 1003.2-1992 (POSIX-2) (includes IEEE Std. 1003.2a-1992) | 38 * The following amendment to the ISO POSIX-2: 1993 standard: | 39 - IEEE P1003.2b draft standard (Additional Utilities) | 40 - IEEE Std. 1003.2d-1994 (Batch Environment) | 41 * Open Group Technical Standard, February 1997, System Interface Definitions, Issue 5 (XBD5) | 42 (ISBN: 1-85912-186-1, C605) | 43 * Open Group Technical Standard, February 1997, Commands and Utilities, Issue 5 (XCU5) | 44 (ISBN: 1-85912-191-8, C604) | 45 * Open Group Technical Standard, February 1997, System Interfaces and Headers, Issue 5 | 46 (XSH5) (in 2 Volumes) (ISBN: 1-85912-181-0, C606) | 47 Note: XBD5, XCU5, and XSH5 are collectively referred to as the Base Specifications. | 48 * Open Group Technical Standard, January 2000, Networking Services, Issue 5.2 (XNS5.2) | 49 (ISBN: 1-85912-241-8, C808) | 50 * ISO/IEC 9899: 1999, Programming Languages - C. | 51 IEEE Std. 1003.1-200x uses the Base Specifications as its organizational basis and adds the | 52 following additional functionality to them drawn from the base documents above: | 53 * Normative text from the ISO POSIX-1: 1996 standard and the ISO POSIX-2: 1993 standard not | 54 included in the Base Specifications | 55 * The amendments to the POSIX.1-1990 standard and the ISO POSIX-2: 1993 standard listed | 56 above, except for parts of IEEE Std. 1003.1g-2000 | 57 * Portability Considerations | 58 * Additional rationale and notes | 59 The following features, marked legacy or obsolescent in the base documents, are not carried | 60 forward into IEEE Std. 1003.1-200x. Other features from the base documents marked legacy or | 61 obsolescent are carried forward unless otherwise noted. | 62 From XSH5, the following legacy interfaces, headers, and external variables are not carried | 63 forward: | 64 advance( ), brk( ), chroot( ), compile( ), cuserid( ), gamma( ), getdtablesize( ), getpagesize( ), getpass( ), | 65 getw( ), putw( ), re_comp( ), re_exec( ), regcmp( ), sbrk( ), sigstack( ), wait3( ), , | 66 , , loc1, _ _loc1, loc2, locs | 67 From XCU5, the following legacy utilities are not carried forward: | 68 calendar, cancel, cc, col, cpio, cu, dircmp, dis, egrep, fgrep, line, lint, lpstat, mail, pack, pcat, pg, spell, | 69 sum, tar, unpack, uulog, uuname, uupick, uuto | 70 In addition, legacy features within non-legacy reference pages (for example, headers) are not | 71 carried forward. | 72 From the ISO POSIX-1: 1996 standard, the following obsolescent features are not carried | 73 forward: | 74 Page 112, CLK_TCK | 75 Page 197 tcgetattr( ) rate returned option | 76 From the ISO POSIX-2: 1993 standard, obsolescent features within the following pages are not | 77 carried forward: | 2 Technical Standard (2000) (Draft July 28, 2000) Introduction Scope 78 Page 75 zero-length prefix within PATH | 79 Page 156, 159 set, | 80 Page 178, awk, use of no argument and no parentheses with length | 81 Page 259, ed | 82 Page 272, env | 83 Page 282, find -perm[-]onum, | 84 Page 295-296, egrep | 85 Page 299-300, head | 86 Page 305-306, join | 87 Page 309-310, kill | 88 Page 431-433, 435-436, sort | 89 Page 444-445, tail | 90 Page 453, 455-456, touch | 91 Page 464-465, tty | 92 Page 472, uniq | 93 Page 515-516, ex | 94 Page 542-543, expand | 95 Page 563-565, more | 96 Page 574-576, newgrp | 97 Page 578, nice | 98 Page 594-596, renice | 99 Page 597-598, split | 100 Page 600-601, strings | 101 Page 624-625, vi | 102 Page 693, lex | 103 The c89 utility (which specified a compiler for the C Language specified by the | 104 ISO/IEC 9899: 1990 standard) has been replaced by a c99 utility (which specifies a compiler for | 105 the C Language specified by the ISO/IEC 9899: 1999 standard). | 106 From XSH5, text marked OH has been reviewed on a case-by-case basis and removed where | 107 appropriate. The XCU5 text marked OF, OP, PI, and UN has been reviewed on a case-by-case | 108 basis and removed where appropriate | 109 For the networking interfaces, the base document is the XNS, Issue 5.2 specification. The | 110 following parts of the XNS, Issue 5.2 specification are out of scope and not included in | 111 IEEE Std. 1003.1-200x: | 112 * Part 3 (XTI) | 113 * Part 4 (Appendixes) | 114 Since there is much duplication between the XNS, Issue 5.2 specification and | 115 IEEE Std. 1003.1g-2000, material only from the following sections of IEEE Std. 1003.1g-2000 has | 116 been considered for inclusion: | 117 * General terms related to sockets (Clause 2.2.2) | 118 * Socket concepts (Clauses 5.1 through 5.3, inclusive) | 119 * The pselect( ) function (Clauses 6.2.2.1 and 6.2.3) | 120 * The isfdtype( ) function (Clause 5.4.8) | 121 * The header (Clause 6.2) | 122 Emphasis is placed on standardizing existing practice for existing users, with changes and | 123 additions limited to correcting deficiencies in the following areas: | Base Definitions, Issue 6 3 Scope Introduction 124 * Issues raised by IEEE or ISO/IEC Interpretations against IEEE Std. 1003.1 and IEEE Std. | 125 1003.2 | 126 * Issues raised in corrigenda for the Base Specifications and working group resolutions from The | 127 Open Group | 128 * Corrigenda and resolutions passed by The Open Group for the XNS, Issue 5.2 specification | 129 * Changes to make the text self-consistent with the additional material merged | 130 * A reorganization of the options in order to facilitate profiling, both for smaller profiles such | 131 as IEEE Std 1003.13, and larger profiles such as the Single UNIX Specification | 132 * Alignment with the ISO/IEC 9899: 1999 standard | 4 Technical Standard (2000) (Draft July 28, 2000) Introduction Conformance 133 1.2 Conformance | 134 Conformance requirements for IEEE Std. 1003.1-200x are defined in Chapter 2 (on page 19). | Base Definitions, Issue 6 5 Normative References Introduction 135 1.3 Normative References | 136 The following standards contain provisions which, through references in this text, constitute | 137 provisions of this volume of IEEE Std. 1003.1-200x. At the time of publication, the editions | 138 indicated were valid. All standards are subject to revision, and parties to agreements based on | 139 this volume of IEEE Std. 1003.1-200x are encouraged to investigate the possibility of applying | 140 the most recent editions of the standards listed below. Members of IEC and ISO maintain | 141 registers of currently valid International Standards. | 142 Notes to Reviewers | 143 This section with side shading will not appear in the final copy. - Ed. | 144 The following list will be updated. | 145 ANS X3.9-1978 | 146 (Reaffirmed 1989) American National Standard Programming Language FORTRAN.1 | 147 ISO/IEC 646 | 148 ISO/IEC 646: 1991, Information Processing - ISO 7-bit Coded Character Set for Information | 149 Interchange.2 | 150 ISO 4217 | 151 ISO 4217: 1995, Codes for the Representation of Currencies and Funds. | 152 ISO/IEC 4873 | 153 ISO/IEC 4873: 1991, Information Technology - ISO 8-bit Code for Information Interchange | 154 - Structure and Rules for Implementation. | 155 ISO 8601 | 156 ISO 8601: 1988, Data Elements and Interchange Formats - Information Interchange - | 157 Representation of Dates and Times. | 158 ISO 8859-1 | 159 ISO 8859-1: 1988, Information Processing - 8-bit Single-byte Coded Graphic Character Sets | 160 - Part 1: Latin Alphabet No. 1. | 161 ISO 8859-2 | 162 ISO 8859-2: 1987, Information Processing - 8-bit Single-byte Coded Graphic Character Sets | 163 - Part 2: Latin Alphabet No. 2. | 164 ISO/IEC 9899 | 165 ISO/IEC 9899: 1999, Programming Languages - C. | 166 ISO/IEC 9945-1 | 167 ISO/IEC 9945-1: 200x, Information Technology - Portable Operating System Interface | 168 (POSIX) - Part 1: System Application Program Interface (API) [C Language] (identical to | 169 ANSI/IEEE Std 1003.1-200x).3 | 170 __________________ | 171 1. ANSI documents can be obtained from the Sales Department, American National Standards Institute, 1430 Broadway, New ||| 172 York, NY 10018, U.S.A. ||| 173 2. ISO/IEC documents can be obtained from the ISO office: 1 Rue de Varembé, Case Postale 56, CH-1211, Genève 20, ||| 174 Switzerland/Suisse ||| 175 3. This standard is available from the IEEE Service Center, 445 Hoes Lane, P.O. Box 1331, Piscataway, NJ 08855-1331, U.S.A. Tel: ||| 176 1 (800) 678-IEEE or +1 (908) 981-1393. ||| 6 Technical Standard (2000) (Draft July 28, 2000) Introduction Normative References 177 ISO/IEC 9945-2 | 178 ISO/IEC 9945-2: 1993, Information Technology - Portable Operating System Interface | 179 (POSIX) - Part 2: Shell and Utilities. | 180 ISO/IEC 10646-1 | 181 ISO/IEC 10646-1: 1993, Information Technology - Universal Multiple-Octet Coded | 182 Character Set (UCS) - Part 1: Architecture and Basic Multilingual Plane. | 183 ISO/IEC 14519: 1999 | 184 ISO/IEC 14519: 1999, Information Technology - POSIX Ada Language Interfaces - | 185 Binding for System Application Program Interface (API) - Realtime Extensions. | Base Definitions, Issue 6 7 Terminology Introduction 186 1.4 Terminology | 187 For the purposes of IEEE Std. 1003.1-200x, the following terminology definitions apply: | 188 can | 189 Describes a permissible optional feature or behavior available to the user or application. The | 190 feature or behavior is mandatory for an implementation that conforms to | 191 IEEE Std. 1003.1-200x. An application can rely on the existence of the feature or behavior. | 192 implementation-defined | 193 Describes a value or behavior that is not defined by IEEE Std. 1003.1-200x but is selected by | 194 an implementor. The value or behavior may vary among implementations that conform to | 195 IEEE Std. 1003.1-200x. An application should not rely on the existence of the value or | 196 behavior. An application that relies on such a value or behavior cannot be assured to be | 197 portable across conforming implementations. | 198 The implementor shall document such a value or behavior so that it can be used correctly | 199 by an application. | 200 legacy | 201 Describes a feature or behavior that is being retained for compatibility with older | 202 applications, but which has limitations which make it inappropriate for developing portable | 203 applications. New applications should use alternative means of obtaining equivalent | 204 functionality. | 205 may | 206 Describes a feature or behavior that is optional for an implementation that conforms to | 207 IEEE Std. 1003.1-200x. An application should not rely on the existence of the feature or | 208 behavior. An application that relies on such a feature or behavior cannot be assured to be | 209 portable across conforming implementations. | 210 To avoid ambiguity, the opposite of may is expressed as need not, instead of may not. | 211 shall | 212 For an implementation that conforms to IEEE Std. 1003.1-200x, describes a feature or | 213 behavior that is mandatory. An application can rely on the existence of the feature or | 214 behavior. | 215 For an application or user, describes a behavior that is mandatory. | 216 should | 217 For an implementation that conforms to IEEE Std. 1003.1-200x, describes a feature or | 218 behavior that is recommended but not mandatory. An application should not rely on the | 219 existence of the feature or behavior. An application that relies on such a feature or behavior | 220 cannot be assured to be portable across conforming implementations. | 221 For an application, describes a feature or behavior that is recommended programming | 222 practice for optimum portability. | 223 undefined | 224 Describes the nature of a value or behavior not defined by IEEE Std. 1003.1-200x which | 225 results from use of an invalid program construct or invalid data input. | 226 The value or behavior may vary among implementations that conform to | 227 IEEE Std. 1003.1-200x. An application should not rely on the existence or validity of the | 228 value or behavior. An application that relies on any particular value or behavior cannot be | 229 assured to be portable across conforming implementations. | 8 Technical Standard (2000) (Draft July 28, 2000) Introduction Terminology 230 unspecified | 231 Describes the nature of a value or behavior not specified by IEEE Std. 1003.1-200x which | 232 results from use of a valid program construct or valid data input. | 233 The value or behavior may vary among implementations that conform to | 234 IEEE Std. 1003.1-200x. An application should not rely on the existence or validity of the | 235 value or behavior. An application that relies on any particular value or behavior cannot be | 236 assured to be portable across conforming implementations. | Base Definitions, Issue 6 9 Portability Introduction 237 1.5 Portability | 238 Some of the utilities in the Shell and Utilities volume of IEEE Std. 1003.1-200x and functions in | 239 the System Interfaces volume of IEEE Std. 1003.1-200x describe functionality that might not be | 240 fully portable to systems meeting the requirements for POSIX conformance (see the Base | 241 Definitions volume of IEEE Std. 1003.1-200x, Chapter 2, Conformance). | 242 Where optional, enhanced, or reduced functionality is specified, the text is shaded and a code in | 243 the margin identifies the nature of the option, extension, or warning (see Section 1.5.1). For | 244 maximum portability, an application should avoid such functionality. | 245 Unless the primary task of a utility is to produce textual material on its standard output, | 246 application developers should not rely on the format or content of any such material that may be | 247 produced. Where the primary task is to provide such material, but the output format is | 248 incompletely specified, the description is marked with the OF margin code and shading. | 249 Application developers are warned not to expect that the output of such an interface on one | 250 system is any guide to its behavior on another system. | 251 1.5.1 Codes | 252 The codes and their meanings are as follows. See also Section 1.5.2 (on page 17). | 253 ADV Advisory Information | 254 The functionality described is optional. The functionality described is also an extension to the | 255 ISO C standard. | 256 Where applicable, functions are marked with the ADV margin legend in the SYNOPSIS section. | 257 Where additional semantics apply to a function, the material is identified by use of the ADV | 258 margin legend. | 259 AIO Asynchronous Input and Output | 260 The functionality described is optional. The functionality described is also an extension to the | 261 ISO C standard. | 262 Where applicable, functions are marked with the AIO margin legend in the SYNOPSIS section. | 263 Where additional semantics apply to a function, the material is identified by use of the AIO | 264 margin legend. | 265 BAR Barriers | 266 The functionality described is optional. The functionality described is also an extension to the | 267 ISO C standard. | 268 Where applicable, functions are marked with the BAR margin legend in the SYNOPSIS section. | 269 Where additional semantics apply to a function, the material is identified by use of the BAR | 270 margin legend. | 271 BE Batch Environment Services and Utilities | 272 The functionality described is optional. | 273 Where applicable, utilities are marked with the BE margin legend in the SYNOPSIS section. | 274 Where additional semantics apply to a utility, the material is identified by use of the BE margin | 275 legend. | 276 CD C-Language Development Utilities | 277 The functionality described is optional. | 278 Where applicable, utilities are marked with the CD margin legend in the SYNOPSIS section. | 279 Where additional semantics apply to a utility, the material is identified by use of the CD margin | 280 legend. | 10 Technical Standard (2000) (Draft July 28, 2000) Introduction Portability 281 CPT Process CPU-Time Clocks | 282 The functionality described is optional. The functionality described is also an extension to the | 283 ISO C standard. | 284 Where applicable, functions are marked with the CPT margin legend in the SYNOPSIS section. | 285 Where additional semantics apply to a function, the material is identified by use of the CPT | 286 margin legend. | 287 CS Clock Selection | 288 The functionality described is optional. The functionality described is also an extension to the | 289 ISO C standard. | 290 Where applicable, functions are marked with the CS margin legend in the SYNOPSIS section. | 291 Where additional semantics apply to a function, the material is identified by use of the CS | 292 margin legend. | 293 CX Extension to the ISO C standard | 294 The functionality described is an extension to the ISO C standard. Application writers may | 295 make use of an extension as it is supported on all IEEE Std. 1003.1-200x-conforming systems. | 296 FD FORTRAN Development Utilities | 297 The functionality described is optional. | 298 Where applicable, utilities are marked with the FD margin legend in the SYNOPSIS section. | 299 Where additional semantics apply to a utility, the material is identified by use of the FD margin | 300 legend. | 301 FR FORTRAN Runtime Utilities | 302 The functionality described is optional. | 303 Where applicable, utilities are marked with the FR margin legend in the SYNOPSIS section. | 304 Where additional semantics apply to a utility, the material is identified by use of the FR margin | 305 legend. | 306 FSC File Synchronization | 307 The functionality described is optional. The functionality described is also an extension to the | 308 ISO C standard. | 309 Where applicable, functions are marked with the FSC margin legend in the SYNOPSIS section. | 310 Where additional semantics apply to a function, the material is identified by use of the FSC | 311 margin legend. | 312 IP6 IPV6 | 313 The functionality described is optional. The functionality described is also an extension to the | 314 ISO C standard. | 315 Where applicable, functions are marked with the IP6 margin legend in the SYNOPSIS section. | 316 Where additional semantics apply to a function, the material is identified by use of the IP6 | 317 margin legend. | 318 MAN Mandatory in the Next Draft | 319 This is an interim draft code used to aid reviewers during the development of | 320 IEEE Std. 1003.1-200x. It denotes a feature that was previously an option or extension that is | 321 being brought into the mandatory base functionality. This margin code will be removed from the | 322 final draft. | 323 MF Memory Mapped Files | 324 The functionality described is optional. The functionality described is also an extension to the | 325 ISO C standard. | Base Definitions, Issue 6 11 Portability Introduction 326 Where applicable, functions are marked with the MF margin legend in the SYNOPSIS section. | 327 Where additional semantics apply to a function, the material is identified by use of the MF | 328 margin legend. | 329 ML Process Memory Locking | 330 The functionality described is optional. The functionality described is also an extension to the | 331 ISO C standard. | 332 Where applicable, functions are marked with the ML margin legend in the SYNOPSIS section. | 333 Where additional semantics apply to a function, the material is identified by use of the ML | 334 margin legend. | 335 MLR Range Memory Locking | 336 The functionality described is optional. The functionality described is also an extension to the | 337 ISO C standard. | 338 Where applicable, functions are marked with the MLR margin legend in the SYNOPSIS section. | 339 Where additional semantics apply to a function, the material is identified by use of the MLR | 340 margin legend. | 341 MON Monotonic Clock | 342 The functionality described is optional. The functionality described is also an extension to the | 343 ISO C standard. | 344 Where applicable, functions are marked with the MON margin legend in the SYNOPSIS section. | 345 Where additional semantics apply to a function, the material is identified by use of the MON | 346 margin legend. | 347 MPR Memory Protection | 348 The functionality described is optional. The functionality described is also an extension to the | 349 ISO C standard. | 350 Where applicable, functions are marked with the MPR margin legend in the SYNOPSIS section. | 351 Where additional semantics apply to a function, the material is identified by use of the MPR | 352 margin legend. | 353 MSG Message Passing | 354 The functionality described is optional. The functionality described is also an extension to the | 355 ISO C standard. | 356 Where applicable, functions are marked with the MSG margin legend in the SYNOPSIS section. | 357 Where additional semantics apply to a function, the material is identified by use of the MSG | 358 margin legend. | 359 OB Obsolescent | 360 The functionality described may be withdrawn in a future version of this volume of | 361 IEEE Std. 1003.1-200x. Strictly Conforming POSIX Applications and Strictly Conforming XSI | 362 Applications shall not use obsolescent features. | 363 OF Output Format Incompletely Specified | 364 The functionality described is an XSI extension. The format of the output produced by the utility | 365 is not fully specified. It is therefore not possible to post-process this output in a consistent | 366 fashion. Typical problems include unknown length of strings and unspecified field delimiters. | 367 OH Optional Header | 368 In the SYNOPSIS section of some interfaces in the System Interfaces volume of | 369 IEEE Std. 1003.1-200x an included header is marked as in the following example: | 12 Technical Standard (2000) (Draft July 28, 2000) Introduction Portability 370 OH #include | 371 #include | 372 struct group *getgrnam(const char *name); | 373 This indicates that the marked header is not required on XSI-conformant systems. | 374 PIO Prioritized Input and Output | 375 The functionality described is optional. The functionality described is also an extension to the | 376 ISO C standard. | 377 Where applicable, functions are marked with the PIO margin legend in the SYNOPSIS section. | 378 Where additional semantics apply to a function, the material is identified by use of the PIO | 379 margin legend. | 380 PS Process Scheduling | 381 The functionality described is optional. The functionality described is also an extension to the | 382 ISO C standard. | 383 Where applicable, functions are marked with the PS margin legend in the SYNOPSIS section. | 384 Where additional semantics apply to a function, the material is identified by use of the PS | 385 margin legend. | 386 RTS Realtime Signals Extension | 387 The functionality described is optional. The functionality described is also an extension to the | 388 ISO C standard. | 389 Where applicable, functions are marked with the RTS margin legend in the SYNOPSIS section. | 390 Where additional semantics apply to a function, the material is identified by use of the RTS | 391 margin legend. | 392 SD Software Development Utilities | 393 The functionality described is optional. | 394 Where applicable, utilities are marked with the SD margin legend in the SYNOPSIS section. | 395 Where additional semantics apply to a utility, the material is identified by use of the SD margin | 396 legend. | 397 SEM Semaphores | 398 The functionality described is optional. The functionality described is also an extension to the | 399 ISO C standard. | 400 Where applicable, functions are marked with the SEM margin legend in the SYNOPSIS section. | 401 Where additional semantics apply to a function, the material is identified by use of the SEM | 402 margin legend. | 403 SHM Shared Memory Objects | 404 The functionality described is optional. The functionality described is also an extension to the | 405 ISO C standard. | 406 Where applicable, functions are marked with the SHM margin legend in the SYNOPSIS section. | 407 Where additional semantics apply to a function, the material is identified by use of the SHM | 408 margin legend. | 409 SIO Synchronized Input and Output | 410 The functionality described is optional. The functionality described is also an extension to the | 411 ISO C standard. | 412 Where applicable, functions are marked with the SIO margin legend in the SYNOPSIS section. | 413 Where additional semantics apply to a function, the material is identified by use of the SIO | 414 margin legend. | Base Definitions, Issue 6 13 Portability Introduction 415 SPI Spin Locks | 416 The functionality described is optional. The functionality described is also an extension to the | 417 ISO C standard. | 418 Where applicable, functions are marked with the SPI margin legend in the SYNOPSIS section. | 419 Where additional semantics apply to a function, the material is identified by use of the SPI | 420 margin legend. | 421 SPN Spawn | 422 The functionality described is optional. The functionality described is also an extension to the | 423 ISO C standard. | 424 Where applicable, functions are marked with the SPN margin legend in the SYNOPSIS section. | 425 Where additional semantics apply to a function, the material is identified by use of the SPN | 426 margin legend. | 427 SS Process Sporadic Server | 428 The functionality described is optional. The functionality described is also an extension to the | 429 ISO C standard. | 430 Where applicable, functions are marked with the SS margin legend in the SYNOPSIS section. | 431 Where additional semantics apply to a function, the material is identified by use of the SS | 432 margin legend. | 433 TCT Thread CPU-Time Clocks | 434 The functionality described is optional. The functionality described is also an extension to the | 435 ISO C standard. | 436 Where applicable, functions are marked with the TCT margin legend in the SYNOPSIS section. | 437 Where additional semantics apply to a function, the material is identified by use of the TCT | 438 margin legend. | 439 THR Threads | 440 The functionality described is optional. The functionality described is also an extension to the | 441 ISO C standard. | 442 Where applicable, functions are marked with the THR margin legend in the SYNOPSIS section. | 443 Where additional semantics apply to a function, the material is identified by use of the THR | 444 margin legend. | 445 TMO Timeouts | 446 The functionality described is optional. The functionality described is also an extension to the | 447 ISO C standard. | 448 Where applicable, functions are marked with the TMO margin legend in the SYNOPSIS section. | 449 Where additional semantics apply to a function, the material is identified by use of the TMO | 450 margin legend. | 451 TMR Timers | 452 The functionality described is optional. The functionality described is also an extension to the | 453 ISO C standard. | 454 Where applicable, functions are marked with the TMR margin legend in the SYNOPSIS section. | 455 Where additional semantics apply to a function, the material is identified by use of the TMR | 456 margin legend. | 457 TPI Threads Priority Inheritance | 458 The functionality described is optional. The functionality described is also an extension to the | 459 ISO C standard. | 14 Technical Standard (2000) (Draft July 28, 2000) Introduction Portability 460 Where applicable, functions are marked with the TPI margin legend in the SYNOPSIS section. | 461 Where additional semantics apply to a function, the material is identified by use of the TPI | 462 margin legend. | 463 TPP Thread Priority Protection | 464 The functionality described is optional. The functionality described is also an extension to the | 465 ISO C standard. | 466 Where applicable, functions are marked with the TPP margin legend in the SYNOPSIS section. | 467 Where additional semantics apply to a function, the material is identified by use of the TPP | 468 margin legend. | 469 TPS Thread Execution Scheduling | 470 The functionality described is optional. The functionality described is also an extension to the | 471 ISO C standard. | 472 Where applicable, functions are marked with the TPS margin legend for the SYNOPSIS section. | 473 Where additional semantics apply to a function, the material is identified by use of the TPS | 474 margin legend. | 475 TRC Trace | 476 The functionality described is optional. The functionality described is also an extension to the | 477 ISO C standard. | 478 Where applicable, functions are marked with the TRC margin legend in the SYNOPSIS section. | 479 Where additional semantics apply to a function, the material is identified by use of the TRC | 480 margin legend. | 481 TEF Trace Event Filter | 482 The functionality described is optional. The functionality described is also an extension to the | 483 ISO C standard. | 484 Where applicable, functions are marked with the TEF margin legend in the SYNOPSIS section. | 485 Where additional semantics apply to a function, the material is identified by use of the TEF | 486 margin legend. | 487 TRL Trace Log | 488 The functionality described is optional. The functionality described is also an extension to the | 489 ISO C standard. | 490 Where applicable, functions are marked with the TRL margin legend in the SYNOPSIS section. | 491 Where additional semantics apply to a function, the material is identified by use of the TRL | 492 margin legend. | 493 TRI Trace Inherit | 494 The functionality described is optional. The functionality described is also an extension to the | 495 ISO C standard. | 496 Where applicable, functions are marked with the TRI margin legend in the SYNOPSIS section. | 497 Where additional semantics apply to a function, the material is identified by use of the TRI | 498 margin legend. | 499 TSA Thread Stack Address Attribute | 500 The functionality described is optional. The functionality described is also an extension to the | 501 ISO C standard. | 502 Where applicable, functions are marked with the TPS margin legend for the SYNOPSIS section. | 503 Where additional semantics apply to a function, the material is identified by use of the TSA | 504 margin legend. | Base Definitions, Issue 6 15 Portability Introduction 505 TSF Thread-Safe Functions | 506 The functionality described is optional. The functionality described is also an extension to the | 507 ISO C standard. | 508 Where applicable, functions are marked with the TSF margin legend in the SYNOPSIS section. | 509 Where additional semantics apply to a function, the material is identified by use of the TSF | 510 margin legend. | 511 TSH Thread Process-Shared Synchronization | 512 The functionality described is optional. The functionality described is also an extension to the | 513 ISO C standard. | 514 Where applicable, functions are marked with the TSH margin legend in the SYNOPSIS section. | 515 Where additional semantics apply to a function, the material is identified by use of the TSH | 516 margin legend. | 517 TSP Thread Sporadic Server | 518 The functionality described is optional. The functionality described is also an extension to the | 519 ISO C standard. | 520 Where applicable, functions are marked with the TSP margin legend in the SYNOPSIS section. | 521 Where additional semantics apply to a function, the material is identified by use of the TSP | 522 margin legend. | 523 TSS Thread Stack Address Size | 524 The functionality described is optional. The functionality described is also an extension to the | 525 ISO C standard. | 526 Where applicable, functions are marked with the TSS margin legend in the SYNOPSIS section. | 527 Where additional semantics apply to a function, the material is identified by use of the TSS | 528 margin legend. | 529 TYM Typed Memory Objects | 530 The functionality described is optional. The functionality described is also an extension to the | 531 ISO C standard. | 532 Where applicable, functions are marked with the TYM margin legend in the SYNOPSIS section. | 533 Where additional semantics apply to a function, the material is identified by use of the TYM | 534 margin legend. | 535 UN Possibly Unsupportable Feature | 536 The functionality described is an XSI extension. It need not be possible to implement the | 537 required functionality (as defined) on all conformant systems and the functionality need not be | 538 present. This may, for example, be the case where the conformant system is hosted and the | 539 underlying system provides the service in an alternative way. | 540 UP User Portability Utilities | 541 The functionality described is optional. | 542 Where applicable, utilities are marked with the UP margin legend in the SYNOPSIS section. | 543 Where additional semantics apply to a utility, the material is identified by use of the UP margin | 544 legend. | 545 XSI Extension | 546 The functionality described is an XSI extension. Functionality marked XSI is also an extension to | 547 the ISO C standard. Application writers may confidently make use of an extension on all | 548 systems supporting the X/Open System Interfaces Extension. | 16 Technical Standard (2000) (Draft July 28, 2000) Introduction Portability 549 If an entire SYNOPSIS section is shaded and marked with one XSI, all the functionality described | 550 in that reference page is an extension. See Section 3.441 (on page 117). | 551 XSR XSI STREAMS | 552 The functionality described is optional. The functionality described is also an extension to the | 553 ISO C standard. | 554 Where applicable, functions are marked with the XSR margin legend in the SYNOPSIS section. | 555 Where additional semantics apply to a function, the material is identified by use of the XSR | 556 margin legend. | 557 1.5.2 Margin Code Notation 558 Some of the functionality described in IEEE Std. 1003.1-200x depends on support of more than 559 one option, or independently may depend on several options. The following notation for margin 560 codes is used to denote the following cases: 561 * A feature dependent on one or two options. | 562 In this case, margin codes have a separator; for example: 563 MF This feature requires support for only the Memory Mapped Files option. | 564 MF SHM This feature requires support for both the Memory Mapped Files and the Shared Memory | 565 Objects options; that is, an application which uses this feature is portable only between | 566 implementations that provide both options. | 567 * A feature dependent on either of the options denoted. 568 In this case, margin codes have a '|' separator to denote the logical OR; for example: 569 MF|SHM This feature is dependent on support for either the Memory Mapped Files option or the | 570 Shared Memory Objects option; that is, an application which uses this feature is portable | 571 between implementations that provide any (or all) of the options. | 572 * A feature dependent on more than two options. | 573 The following special notations are used: | 574 code1 ADV (MF|SHM) This feature requires support of the Advisory Informtion option and either | 575 the Memory Mapped Files or Shared Memory Objects option. | 576 code2 MF|SHM|MPR This feature requires support of either the Memory Mapped Files, Shared | 577 Memory Objects, or Memory Protection options. | 578 Where large sections of text are dependent on support for an option, a lead-in text block is | 579 provided and shaded accordingly; for example: | 580 TRC This section describes extensions to support tracing of user applications. This functionality is | 581 dependent on support of the Trace option (and the rest of this section is not further shaded for | 582 this option). | Base Definitions, Issue 6 17 Introduction 18 Technical Standard (2000) (Draft July 28, 2000) Chapter 2 Conformance 583 584 2.1 Implementation Conformance 585 2.1.1 Requirements 586 A conforming implementation shall meet all of the following criteria: 587 1. The system shall support all utilities, functions, and facilities defined within 588 IEEE Std. 1003.1-200x that are required for POSIX conformance (see Section 2.1.3 (on page 589 20)). These interfaces shall support the functional behavior described herein. 590 2. The system may support one or more options as described under Section 2.1.5 (on page 591 25). When an implementation claims that an option is supported, all of its constituent 592 parts shall be provided. 593 3. The system may support the X/Open System Interface Extension (XSI) as described under 594 Section 2.1.4 (on page 23). 595 4. The system may provide additional utilities, functions, or facilities not required by 596 IEEE Std. 1003.1-200x. Non-standard extensions of the utilities, functions, or facilities 597 specified in IEEE Std. 1003.1-200x should be identified as such in the system 598 documentation. Non-standard extensions, when used, may change the behavior of utilities, 599 functions, or facilities defined by IEEE Std. 1003.1-200x. The conformance document shall 600 define an environment in which an application can be run with the behavior specified by 601 IEEE Std. 1003.1-200x. In no case shall such an environment require modification of a 602 Strictly Conforming POSIX Application (see Section 2.2.1 (on page 38)). 603 2.1.2 Documentation 604 A conformance document with the following information shall be available for an 605 implementation claiming conformance to IEEE Std. 1003.1-200x. The conformance document 606 shall have the same structure as IEEE Std. 1003.1-200x, with the information presented in the 607 appropriate sections and subsections. Sections and subsections that consist solely of subordinate 608 section titles, with no other information, are not required. The conformance document shall not 609 contain information about extended facilities or capabilities outside the scope of 610 IEEE Std. 1003.1-200x. 611 The conformance document shall contain a statement that indicates the full name, number, and 612 date of the standard that applies. The conformance document may also list international 613 software standards that are available for use by a Conforming POSIX Application. Applicable 614 characteristics where documentation is required by one of these standards, or by standards of 615 government bodies, may also be included. 616 The conformance document shall describe the limit values found in the headers (on 617 page 281) and (on page 437), stating values, the conditions under which those values 618 may change, and the limits of such variations, if any. 619 The conformance document shall describe the behavior of the implementation for all | 620 implementation-defined features defined in IEEE Std. 1003.1-200x. This requirement shall be met | 621 by listing these features and providing either a specific reference to the system documentation or 622 providing full syntax and semantics of these features. When the value or behavior in the Base Definitions, Issue 6 19 Implementation Conformance Conformance 623 implementation is designed to be variable or customized on each instantiation of the system, the 624 implementation provider shall document the nature and permissible ranges of this variation. 625 The conformance document may specify the behavior of the implementation for those features 626 where IEEE Std. 1003.1-200x states that implementations may vary or where features are 627 identified as undefined or unspecified. 628 The conformance document shall not contain documentation other than that specified in the 629 preceding paragraph except where such documentation is specifically allowed or required by 630 other provisions of IEEE Std. 1003.1-200x. 631 The phrases ``shall document'' or ``shall be documented'' in IEEE Std. 1003.1-200x mean that 632 documentation of the feature shall appear in the conformance document, as described 633 previously, unless there is an explicit reference in the conformance document to show where the 634 information can be found in the system documentation. 635 The system documentation should also contain the information found in the conformance 636 document. 637 2.1.3 POSIX Conformance 638 A conforming implementation shall meet the following criteria for POSIX conformance. | 639 2.1.3.1 POSIX System Interfaces 640 * The system shall set the symbolic constant _POSIX_BASE to a value other than -1. | 641 * The system shall support the following symbolic constants, reflecting mandatory Profiling 642 Option Groups for IEEE Std. 1003.1-200x (see Section 2.1.5 (on page 25)): 643 - _POSIX_C_LANG_SUPPORT 644 - _POSIX_DEVICE_IO 645 - _POSIX_DEVICE_SPECIFIC 646 - _POSIX_FD_MGMT 647 - _POSIX_FIFO 648 - _POSIX_FILE_ATTRIBUTES 649 - _POSIX_FILE_SYSTEM 650 - _POSIX_JOB_CONTROL 651 - _POSIX_MULTIPLE_PROCESS 652 - _POSIX_PIPE 653 - _POSIX_SIGNALS 654 - _POSIX_SINGLE_PROCESS 655 - _POSIX_SYSTEM_DATABASE 656 - _POSIX_USER_GROUPS 657 - _POSIX_NETWORKING 658 * The system may support one or more Profiling Option Groups (see Section 2.1.5.1 (on page 659 25)) denoted by the following symbolic constants: 20 Technical Standard (2000) (Draft July 28, 2000) Conformance Implementation Conformance 660 - _POSIX_C_LANG_SUPPORT_R 661 - _POSIX_FILE_LOCKING 662 - _POSIX_SYSTEM_DATABASE_R 663 - _POSIX_USER_GROUPS_R 664 * Although all implementations conforming to IEEE Std. 1003.1-200x support all the features 665 described below, there may be system-dependent or file system-dependent configuration 666 procedures that can remove or modify any or all of these features. Such configurations 667 should not be made if strict compliance is required. 668 The following symbolic constants shall either be undefined or defined with a value other 669 than -1. If a constant is undefined, an application should use the sysconf( ), pathconf( ), or 670 fpathconf( ) functions, or the getconf utility, to determine which features are present on the 671 system at that time or for the particular path name in question. 672 - _POSIX_CHOWN_RESTRICTED 673 The use of chown( ) is restricted to a process with appropriate privileges, and to changing 674 the group ID of a file only to the effective group ID of the process or to one of its 675 supplementary group IDs. 676 - _POSIX_NO_TRUNC 677 Path name components longer than {NAME_MAX} generate an error. 678 * The following symbolic constants shall be defined with a value other than -1: 679 - _POSIX_JOB_CONTROL | 680 - _POSIX_SAVED_IDS | 681 - _POSIX_VDISABLE | 682 Note: The symbols above represent historical options that are no longer allowed as | 683 options, but are retained here for backwards-compatibility of applications. | 684 * The system may support one or more options (see Section 2.1.6 (on page 32)) denoted by the | 685 following symbolic constants: 686 - _POSIX_ADVISORY_INFO 687 - _POSIX_ASYNCHRONOUS_IO 688 - _POSIX_BARRIERS 689 - _POSIX_CLOCK_SELECTION 690 - _POSIX_CPUTIME 691 - _POSIX_FSYNC 692 - _POSIX_IPV6 693 - _POSIX_MAPPED_FILES 694 - _POSIX_MEMLOCK 695 - _POSIX_MEMLOCK_RANGE 696 - _POSIX_MEMORY_PROTECTION 697 - _POSIX_MESSAGE_PASSING Base Definitions, Issue 6 21 Implementation Conformance Conformance 698 - _POSIX_MONOTONIC_CLOCK 699 - _POSIX_PRIORITIZED_IO 700 - _POSIX_PRIORITY_SCHEDULING 701 - _POSIX_RAW_SOCKETS 702 - _POSIX_REALTIME_SIGNALS | 703 - _POSIX_SEMAPHORES 704 - _POSIX_SHARED_MEMORY_OBJECTS 705 - _POSIX_SPAWN 706 - _POSIX_SPIN_LOCKS 707 - _POSIX_SPORADIC_SERVER 708 - _POSIX_SYNCHRONIZED_IO 709 - _POSIX_THREAD_ATTR_STACKADDR 710 - _POSIX_THREAD_CPUTIME 711 - _POSIX_THREAD_ATTR_STACKSIZE 712 - _POSIX_THREAD_PRIO_INHERIT 713 - _POSIX_THREAD_PRIO_PROTECT 714 - _POSIX_THREAD_PRIORITY_SCHEDULING 715 - _POSIX_THREAD_PROCESS_SHARED 716 - _POSIX_THREAD_SAFE_FUNCTIONS 717 - _POSIX_THREAD_SPORADIC_SERVER 718 - _POSIX_THREADS 719 - _POSIX_TIMEOUTS 720 - _POSIX_TIMERS 721 - _POSIX_TRACE | 722 - _POSIX_TRACE_EVENT_FILTER | 723 - _POSIX_TRACE_INHERIT | 724 - _POSIX_TRACE_LOG | 725 - _POSIX_TYPED_MEMORY_OBJECTS | 726 If any of the symbolic constants _POSIX_TRACE_EVENT_FILTER, _POSIX_TRACE_LOG, or | 727 _POSIX_TRACE_INHERIT is defined to have a value other than -1, then the symbolic | 728 constant _POSIX_TRACE shall also be defined to have a value other than -1. | 729 XSI * The system may support the XSI extensions (see Section 2.1.5.2 (on page 27)) denoted by the 730 following symbolic constants: 731 - _XOPEN_CRYPT 732 - _XOPEN_LEGACY 22 Technical Standard (2000) (Draft July 28, 2000) Conformance Implementation Conformance 733 - _XOPEN_REALTIME 734 - _XOPEN_REALTIME_THREADS 735 - _XOPEN_UNIX 736 2.1.3.2 POSIX Shell and Utilities 737 * The system shall provide all the mandatory utilities in the Shell and Utilities volume of | 738 IEEE Std. 1003.1-200x with all the functional behavior described therein. | 739 * The system shall support the Large File capabilities described in the Shell and Utilities | 740 volume of IEEE Std. 1003.1-200x. | 741 * The system may support one or more options (see Section 2.1.6 (on page 32)) denoted by the 742 following symbolic constants. (The literal names below apply to the getconf utility.) 743 - POSIX2_C_DEV 744 - POSIX2_CHAR_TERM 745 - POSIX2_FORT_DEV 746 - POSIX2_FORT_RUN 747 - POSIX2_LOCALEDEF 748 - POSIX2_PBS 749 - POSIX2_PBS_ACCOUNTING 750 - POSIX2_PBS_LOCATE 751 - POSIX2_PBS_MESSAGE 752 - POSIX2_PBS_TRACK 753 - POSIX2_SW_DEV 754 - POSIX2_UPE 755 * The system may support the XSI extensions (see Section 2.1.4). 756 Additional language bindings and development utility options may be provided in other related 757 standards or in a future version of IEEE Std. 1003.1-200x. In the former case, additional symbolic 758 constants of the same general form as shown in this subsection should be defined by the related 759 standard document and made available to the application without requiring 760 IEEE Std. 1003.1-200x to be updated. 761 2.1.4 XSI Conformance 762 XSI IEEE Std. 1003.1-200x describes utilities, functions, and facilities offered to application programs 763 by the X/Open System Interface (XSI). An XSI-conforming implementation shall meet the 764 criteria for POSIX conformance and the following requirements. 765 2.1.4.1 XSI System Interfaces 766 * The system shall support all the functions and headers defined in IEEE Std. 1003.1-200x as 767 part of the XSI extension denoted by the symbolic constant _XOPEN_UNIX and any 768 extensions marked with the XSI extension marking (see Section 1.5.1 (on page 10)). 769 * The system shall support the mmap( ), munmap( ), and msync( ) functions. Base Definitions, Issue 6 23 Implementation Conformance Conformance 770 * The system shall support the following options defined within IEEE Std. 1003.1-200x (see 771 Section 2.1.6 (on page 32)): 772 - _POSIX_FSYNC 773 - _POSIX_MAPPED_FILES 774 - _POSIX_MEMORY_PROTECTION 775 - _POSIX_THREAD_ATTR_STACKADDR | 776 - _POSIX_THREAD_ATTR_STACKSIZE 777 - _POSIX_THREAD_PROCESS_SHARED 778 - _POSIX_THREAD_SAFE_FUNCTIONS 779 - _POSIX_THREADS 780 * The system shall support the following Profiling Option Groups (see Section 2.1.5.1 (on page 781 25)) defined within IEEE Std. 1003.1-200x: 782 - _POSIX_C_LANG_SUPPORT_R 783 - _POSIX_FILE_LOCKING 784 - _POSIX_SYSTEM_DATABASE_R 785 - _POSIX_USER_GROUPS_R 786 * The system may support the following XSI Option Groups (see Section 2.1.5.2 (on page 27)) 787 defined within IEEE Std. 1003.1-200x: 788 - _XOPEN_CRYPT 789 - _XOPEN_LEGACY 790 - _XOPEN_REALTIME 791 - _XOPEN_REALTIME_THREADS 792 2.1.4.2 XSI Shell and Utilities Conformance 793 * The system shall support all the utilities defined in the Shell and Utilities volume of | 794 IEEE Std. 1003.1-200x as part of the XSI extension denoted by the XSI marking in the | 795 SYNOPSIS section, and any extensions marked with the XSI extension marking (see Section 796 1.5.1 (on page 10)) within the text. 797 * The system shall support the User Portability Utilities option. 798 * The system shall support creation of locales (see Chapter 7 (on page 143)). 799 * The C-language Development utility c99 shall be supported. | 800 * The XSI Development Utilities option may be supported. It consists of the following software 801 development utilities: 802 admin delta | rmdel val | | | ||||| 803 cflow get sact| | what | | |||| 804 ctags m4 sccs| | | ||| 805 cxref prs | unget | | ||| 806 * Within the utilities that are provided, functionality marked by the codes OF, OP, PI, or UN 807 (see Section 1.5.1 (on page 10)) need not be provided. 808 24 Technical Standard (2000) (Draft July 28, 2000) Conformance Implementation Conformance 809 2.1.5 Option Groups 810 An Option Group is a group of related functions or options defined within the System Interfaces 811 volume of IEEE Std. 1003.1-200x. 812 If an implementation supports an Option Group, then the system shall support the functional 813 behavior described herein. 814 If an implementation does not support an Option Group, then the system need not support the 815 functional behavior described herein. 816 2.1.5.1 Profiling Option Groups 817 The following Option Groups are defined to support profiling. These Option Groups allow 818 profiles to subset the System Interfaces volume of IEEE Std. 1003.1-200x by defining sets of 819 functions, denoted by the following symbolic constants: 820 _POSIX_C_LANG_SUPPORT: General C Library Support 821 abs( ), acos( ), asctime( ), asin( ), atan( ), atan2( ), atof( ), atoi( ), atol( ), bsearch( ), calloc( ), ceil( ), 822 cos( ), cosh( ), ctime( ), exp( ), fabs( ), floor( ), fmod( ), free( ), frexp( ), gmtime( ), idexp( ), isalnum( ), 823 isalpha( ), iscntrl( ), isdigit( ), isgraph( ), islower( ), isprint( ), ispunct( ), isspace( ), isupper( ), 824 isxdigit( ), localtime( ), log( ), log10( ), longjmp( ), malloc( ), mktime( ), modf( ), pow( ), qsort( ), 825 rand( ), realloc( ), setjmp( ), sin( ), sinh( ), sqrt( ), srand( ), strcat( ), strchr( ), strcmp( ), strcpy( ), 826 strcspn( ), strlen( ), strncat( ), strncmp( ), strncpy( ), strpbkr( ), strrchr( ), strspn( ), strstr( ), 827 strtok( ), tan( ), tanh( ), tolower( ), toupper( ) 828 _POSIX_C_LANG_SUPPORT_R: Thread-Safe C-Language Support 829 asctime_r( ), ctime_r( ), gmtime_r( ), localtime_r( ), readdir_r( ), rand_r( ), strtok_r( ) 830 _POSIX_DEVICE_IO: Device Input and Output 831 close( ), clearerr( ), getc( ), getchar( ), gets( ), fclose( ), fdopen( ), feof( ), ferror( ), fflush( ), fgetc( ), 832 fgets( ), fileno( ), fopen( ), fprintf( ), fputc( ), fputs( ), fread( ), freopen( ), fscanf( ), fwrite( ), open( ), 833 perror( ), printf( ), putc( ), putchar( ), puts( ), read( ), sprintf( ), scanf( ), sscanf( ), setbuf( ), 834 ungetc( ), write( ) 835 _POSIX_DEVICE_SPECIFIC: General Terminal Interface 836 cfgetospeed( ), cfsetispeed( ), cfsetospeed( ), ctermid( ), isatty( ), tcgetattr( ), tcsetattr( ), 837 tcsendbreak( ), tcdrain( ), tcflush( ), tcflow( ), ttyname( ) 838 _POSIX_DEVICE_SPECIFIC_R: Thread-Safe General Terminal Interface 839 ttyname_r( ) 840 _POSIX_FD_MGMT: File Descriptor 841 dup( ), dup2( ), fcntl( ), fseek( ), ftell( ), lseek( ), rewind( ) 842 _POSIX_FIFO: FIFO 843 mkfifo( ) 844 _POSIX_FILE_ATTRIBUTES: File Attributes 845 chmod( ), chown( ), umask( ) 846 _POSIX_FILE_LOCKING: Thread-Safe Stdio Locking 847 flockfile ( ), ftrylockfile ( ), funlockfile ( ), getc_unlocked( ), getchar_unlocked( ), putc_unlocked( ), 848 putchar_unlocked( ) 849 _POSIX_FILE_SYSTEM: File System 850 access( ), chdir( ), closedir( ), creat( ), fpathconf( ), fstat( ), getcwd( ), link( ), mkdir( ), opendir( ), 851 pathconf( ), readdir( ), remove( ), rename( ), rewinddir( ), rmdir( ), stat( ), tmpfile( ), tmpnam( ), 852 unlink( ), utime( ) Base Definitions, Issue 6 25 Implementation Conformance Conformance 853 _POSIX_JOB_CONTROL: Job Control 854 setpgid( ), tcgetpgrp( ), tcsetpgrp( ) 855 _POSIX_MULTIPLE_PROCESS: Multiple Process 856 _exit( ), assert( ), exit( ), execl( ), execle( ), execlp( ), execv( ), execve( ), execvp( ), fork( ), getenv( ), 857 getpid( ), getppid( ), setlocale( ), sleep( ), times( ), wait( ), waitpid( ) 858 _POSIX_NETWORKING: Networking 859 accept( ), bind( ), connect( ), endhostent( ), endnetent( ), endprotoent( ), endservent( ), getaddrinfo( ), 860 gethostbyaddr( ), gethostbyname( ), gethostent( ), gethostname( ), getipnodebyaddr( ), 861 getipnodebyname( ), getnameinfo( ), getnetbyaddr( ), getnetbyname( ), getnetent( ), getpeername( ), 862 getprotobyname( ), getprotobynumber( ), getprotoent( ), getservbyname( ), getservbyport( ), 863 getservent( ), getsockname( ), getsockopt( ), htonl( ), htons( ), if_freenameindex( ), if_indextoname( ), 864 if_nameindex( ), if_nametoindex( ), inet_addr( ), inet_lnaof( ), inet_makeaddr( ), inet_netof( ), 865 inet_network( ), inet_ntoa( ), listen( ), ntohl( ), ntohs( ), recv( ), recvfrom( ), recvmsg( ), send( ), 866 sendmsg( ), sendto( ), sethostent( ), setnetent( ), setprotoent( ), setservent( ), setsockopt( ), 867 shutdown( ), socket( ), socketpair( ) 868 _POSIX_PIPE: Pipe 869 pipe( ) 870 _POSIX_SIGNALS: Signal 871 abort( ), alarm( ), kill( ), pause( ), sigaction( ), sigaddset( ), sigdelset( ), sigemptyset( ), sigfillset( ), 872 sigismember( ), siglongjmp( ), sigpending( ), sigprocmask( ), sigsuspend( ), sigsetjmp( ) 873 _POSIX_SINGLE_PROCESS: Single Process 874 sysconf( ), time( ), uname( ) 875 _POSIX_SYSTEM_DATABASE: System Database 876 getgrgid( ), getgrnam( ), getpwnam( ), getpwuid( ) 877 _POSIX_SYSTEM_DATABASE_R: Thread-Safe System Database 878 getgrgid_r( ), getgrnam_r( ), getpwuid_r( ), getpwnam_r( ) 879 _POSIX_USER_GROUPS: User and Group 880 geteuid( ), getegid( ), getgid( ), getgroups( ), getlogin( ), getpgrp( ), getuid( ), setgid( ), setsid( ), 881 setuid( ) 882 _POSIX_USER_GROUPS_R: Thread-Safe User and Group 883 getlogin_r( ) 884 Many of these profiling option groups provide basic system functionality that other profiling | 885 option groups and options depend upon.4 All of the mandatory profiling option groups (listed in | 886 Section 2.1.3.1 (on page 20)) shall be supported by an implementation conforming to | 887 IEEE Std. 1003.1-200x. If a profile of IEEE Std. 1003.1-200x does not require an implementation to | 888 provide all of the mandatory profiling option groups or does not require an implementation to | 889 provide an option or profiling option group that provides features required by another option or | 890 profiling option group,5 the profile shall specify6 all of the following: | 891 __________________ | 892 4. As an example, the File System profiling option group provides underlying support for path name resolution and file creation ||| 893 which are needed by any interface in IEEE Std. 1003.1-200x that parses a path argument. If a profile requires support for the ||| 894 Device Input and Output profiling option group but does not require support for the File System profiling option group, the ||| 895 profile must specify how path name resolution is to behave in that profile, how the O_CREAT flag to open( ) is to be handled (and ||| 896 the use of the character 'a' in the mode argument of fopen( ) when a file name argument names a file that does not exist), and ||| 897 specify lots of other details. ||| 898 5. As an example, IEEE Std. 1003.1-200x requires that implementations claiming to support the Range Memory Locking option also ||| 899 support the Process Memory Locking option. A profile could require that the Range Memory Locking option had to be supplied ||| 900 without requiring that the Process Memory Locking option be supplied as long as the profile specifies everything an application ||| 901 writer or system implementor would have to know to build an application or implementation conforming to the profile. ||| 26 Technical Standard (2000) (Draft July 28, 2000) Conformance Implementation Conformance 902 * Restricted or altered behavior of interfaces defined by IEEE Std. 1003.1-200x that may differ | 903 on an implementation of the profile | 904 * Additional behaviors that may produce undefined or unspecified results | 905 * Additional implementation-defined behavior that implementations shall be required to | 906 document in the profile's conformance document | 907 if any of the above is a result of the profile not providing an interface required by | 908 IEEE Std. 1003.1-200x. | 909 2.1.5.2 XSI Option Groups 910 XSI The following Option Groups are defined to support the definition of XSI conformance within 911 the System Interfaces volume of IEEE Std. 1003.1-200x: 912 Encryption 913 The Encryption Option Group is denoted by the symbolic constant _XOPEN_CRYPT. It includes 914 the following functions: 915 crypt( ), encrypt( ), setkey( ) | 916 These functions are marked CRYPT. 917 Due to U.S. Government export restrictions on the decoding algorithm, implementations are 918 restricted in making these functions available. All the functions in the Encryption Option Group 919 may therefore return [ENOSYS] or, alternatively, encrypt( ) shall return [ENOSYS] for the 920 decryption operation. 921 An implementation that claims conformance to this Option Group shall set the symbolic 922 constant _XOPEN_CRYPT to a value other than -1. 923 Realtime 924 The Realtime Option Group is denoted by the symbolic constant _XOPEN_REALTIME. 925 This Option Group includes a set of realtime functions drawn from options within 926 IEEE Std. 1003.1-200x (see Section 2.1.6 (on page 32)). 927 Where entire functions are included in the Option Group, the NAME section is marked with 928 REALTIME. Where additional semantics have been added to existing pages, the new material is 929 identified by use of the appropriate margin legend for the underlying option defined within 930 IEEE Std. 1003.1-200x. 931 An implementation that claims conformance to this Option Group shall set the symbolic 932 constant _XOPEN_REALTIME to a value other than -1. 933 This Option Group consists of the set of the following options from within IEEE Std. 1003.1-200x 934 (see Section 2.1.6 (on page 32)): | 935 ___________________________________________________________________________________________________________________ | 936 6. 6. Note that the profile could just specify that any use of the features not specified by the profile would produce undefined or |||||| 937 unspecified results. |||||| Base Definitions, Issue 6 27 Implementation Conformance Conformance 938 _POSIX_ASYNCHRONOUS_IO | 939 _POSIX_FSYNC | 940 _POSIX_MAPPED_FILES | 941 _POSIX_MEMLOCK | 942 _POSIX_MEMLOCK_RANGE | 943 _POSIX_MEMORY_PROTECTION | 944 _POSIX_MESSAGE_PASSING | 945 _POSIX_PRIORITIZED_IO | 946 _POSIX_PRIORITY_SCHEDULING | 947 _POSIX_REALTIME_SIGNALS | 948 _POSIX_SEMAPHORES | 949 _POSIX_SHARED_MEMORY_OBJECTS | 950 _POSIX_SYNCHRONIZED_IO | 951 _POSIX_TIMERS | 952 If the symbolic constant _XOPEN_REALTIME is defined to have a value other than -1, then the | 953 following symbolic constants shall be defined by the implementation to have the value | 954 200ymmL, the date of approval of IEEE Std. 1003.1-200x: | 955 _POSIX_ASYNCHRONOUS_IO | 956 _POSIX_MEMLOCK | 957 _POSIX_MEMLOCK_RANGE | 958 _POSIX_MESSAGE_PASSING | 959 _POSIX_PRIORITY_SCHEDULING | 960 _POSIX_REALTIME_SIGNALS | 961 _POSIX_SEMAPHORES | 962 _POSIX_SHARED_MEMORY_OBJECTS | 963 _POSIX_SYNCHRONIZED_IO | 964 _POSIX_TIMERS | 965 The functionality associated with _POSIX_MAPPED_FILES, _POSIX_MEMORY_PROTECTION, 966 and _POSIX_FSYNC is always supported on XSI-conformant systems. 967 Support of _POSIX_PRIORITIZED_IO on XSI-conformant systems is optional. If this 968 functionality is supported, then _POSIX_PRIORITIZED_IO shall be set to a value other than -1. 969 Otherwise, it shall be undefined. 970 If _POSIX_PRIORITIZED_IO is supported, then asynchronous I/O operations performed by | 971 aio_read( ), aio_write( ), and lio_listio ( ) shall be submitted at a priority equal to the scheduling 972 priority of the process minus aiocbp->aio_reqprio. The implementation shall also document for | 973 which files I/O prioritization is supported. | 974 Advanced Realtime | 975 An implementation that claims conformance to this Option Group shall also support the | 976 Realtime Option Group. | 977 Where entire functions are included in the Option Group, the NAME section is marked with | 978 ADVANCED REALTIME. Where additional semantics have been added to existing pages, the | 979 new material is identified by use of the appropriate margin legend for the underlying option | 980 defined within IEEE Std. 1003.1-200x. | 981 This Option Group consists of the set of the following options from within IEEE Std. 1003.1-200x | 982 (see Section 2.1.6 (on page 32)): | 28 Technical Standard (2000) (Draft July 28, 2000) Conformance Implementation Conformance 983 _POSIX_ADVISORY_INFO || 984 _POSIX_CLOCK_SELECTION || 985 _POSIX_CPUTIME || 986 _POSIX_MONOTONIC_CLOCK || 987 _POSIX_SPAWN || 988 _POSIX_SPORADIC_SERVER || 989 _POSIX_TIMEOUTS || 990 _POSIX_TYPED_MEMORY_OBJECTS || 991 If the implementation supports the Advanced Realtime Option Group, then the following | 992 symbolic constants shall be defined by the implementation to have the value 200ymmL, the date | 993 of approval of IEEE Std. 1003.1-200x: | 994 _POSIX_ADVISORY_INFO || 995 _POSIX_CLOCK_SELECTION || 996 _POSIX_CPUTIME || 997 _POSIX_MONOTONIC_CLOCK || 998 _POSIX_SPAWN || 999 _POSIX_SPORADIC_SERVER || 1000 _POSIX_TIMEOUTS || 1001 _POSIX_TYPED_MEMORY_OBJECTS || 1002 If the symbolic constant _POSIX_SPORADIC_SERVER is defined, then the symbolic constant | 1003 _POSIX_PRIORITY_SCHEDULING shall also be defined by the implementation to have the | 1004 value 200ymmL, the date of approval of IEEE Std. 1003.1-200x. | 1005 If the symbolic constant _POSIX_CPUTIME is defined, then the symbolic constant | 1006 _POSIX_TIMERS shall also be defined by the implementation to have the value 200ymmL, the | 1007 date of approval of IEEE Std. 1003.1-200x. | 1008 If the symbolic constant _POSIX_MONOTONIC_CLOCK is defined, then the symbolic constant | 1009 _POSIX_TIMERS shall also be defined by the implementation to have the value 200ymmL, the | 1010 date of approval of IEEE Std. 1003.1-200x. | 1011 If the symbolic constant _POSIX_CLOCK_SELECTION is defined, then the symbolic constant | 1012 _POSIX_TIMERS shall also be defined by the implementation to have the value 200ymmL, the | 1013 date of approval of IEEE Std. 1003.1-200x. | 1014 Realtime Threads 1015 The Realtime Threads Option Group is denoted by the symbolic constant | 1016 _XOPEN_REALTIME_THREADS. 1017 This Option Group consists of the set of the following options from within IEEE Std. 1003.1-200x | 1018 (see Section 2.1.6 (on page 32)): | 1019 _POSIX_THREAD_PRIO_INHERIT | 1020 _POSIX_THREAD_PRIO_PROTECT | 1021 _POSIX_THREAD_PRIORITY_SCHEDULING | 1022 Where applicable, whole pages are marked REALTIME THREADS, together with the | 1023 appropriate option margin legend for the SYNOPSIS section (see Section 1.5.1 (on page 10)). | 1024 An implementation that claims conformance to this Option Group shall set | 1025 _XOPEN_REALTIME_THREADS to a value other than -1. | 1026 If the symbol _XOPEN_REALTIME_THREADS is defined to have a value other than -1, then the | 1027 symbols shall also be defined by the implementation to have the value 200ymmL, the date of | Base Definitions, Issue 6 29 Implementation Conformance Conformance 1028 approval of IEEE Std. 1003.1-200x: | 1029 _POSIX_THREAD_PRIO_INHERIT || 1030 _POSIX_THREAD_PRIO_PROTECT || 1031 _POSIX_THREAD_PRIORITY_SCHEDULING || 1032 Advanced Realtime Threads | 1033 An implementation that claims conformance to this Option Group shall also support the | 1034 Realtime Threads Option Group. | 1035 Where entire functions are included in the Option Group, the NAME section is marked with | 1036 ADVANCED REALTIME THREADS. Where additional semantics have been added to existing | 1037 pages, the new material is identified by use of the appropriate margin legend for the underlying | 1038 option defined within IEEE Std. 1003.1-200x. | 1039 This Option Group consists of the set of the following options from within IEEE Std. 1003.1-200x | 1040 (see Section 2.1.6 (on page 32)): | 1041 _POSIX_BARRIERS || 1042 _POSIX_SPIN_LOCKS || 1043 _POSIX_THREAD_CPUTIME || 1044 _POSIX_THREAD_SPORADIC_SERVER || 1045 If the symbolic constant _POSIX_THREAD_SPORADIC_SERVER is defined, then the symbolic | 1046 constant _POSIX_THREAD_PRIORITY_SCHEDULING shall also be defined by the | 1047 implementation to have the value 200ymmL, the date of approval of IEEE Std. 1003.1-200x. | 1048 If the symbolic constant _POSIX_THREAD_CPUTIME is defined, then the symbolic constant | 1049 _POSIX_TIMERS shall also be defined by the implementation to have the value 200ymmL, the | 1050 date of approval of IEEE Std. 1003.1-200x. | 1051 If the symbolic constant _POSIX_BARRIERS is defined, then the symbolic constants | 1052 _POSIX_THREADS and _POSIX_THREAD_SAFE_FUNCTIONS shall also be defined by the | 1053 implementation to have the value 200ymmL, the date of approval of IEEE Std. 1003.1-200x. | 1054 If the symbolic constant _POSIX_SPIN_LOCKS is defined, then the symbolic constants | 1055 _POSIX_THREADS and _POSIX_THREAD_SAFE_FUNCTIONS shall also be defined by the | 1056 implementation to have the value 200ymmL, the date of approval of IEEE Std. 1003.1-200x. | 1057 If the implementation supports the Advanced Realtime Threads Option Group, then the | 1058 following symbolic constants shall be defined by the implementation to have the value | 1059 200ymmL, the date of approval of IEEE Std. 1003.1-200x: | 1060 _POSIX_BARRIERS | 1061 _POSIX_SPIN_LOCKS | 1062 _POSIX_THREAD_CPUTIME | 1063 _POSIX_THREAD_SPORADIC_SERVER | 30 Technical Standard (2000) (Draft July 28, 2000) Conformance Implementation Conformance 1064 Tracing | 1065 This Option Group includes a set of tracing functions drawn from options within | 1066 IEEE Std. 1003.1-200x (see Section 2.1.6 (on page 32)). | 1067 Where entire functions are included in the Option Group, the NAME section is marked with | 1068 TRACING. Where additional semantics have been added to existing pages, the new material is | 1069 identified by use of the appropriate margin legend for the underlying option defined within | 1070 IEEE Std. 1003.1-200x. | 1071 This Option Group consists of the set of the following options from within IEEE Std. 1003.1-200x | 1072 (see Section 2.1.6 (on page 32)): | 1073 _POSIX_TRACE || 1074 _POSIX_TRACE_EVENT_FILTER || 1075 _POSIX_TRACE_LOG || 1076 _POSIX_TRACE_INHERIT || 1077 If the implementation supports the Tracing Option Group, then the following symbolic | 1078 constants shall be defined by the implementation to have the value 200ymmL, the date of | 1079 approval of IEEE Std. 1003.1-200x: | 1080 _POSIX_TRACE || 1081 _POSIX_TRACE_EVENT_FILTER || 1082 _POSIX_TRACE_LOG || 1083 _POSIX_TRACE_INHERIT || 1084 XSI STREAMS | 1085 The XSI STREAMS Option Group is denoted by the symbolic constant _XOPEN_STREAMS. 1086 This Option Group includes functionality related to STREAMS, a uniform mechanism for 1087 implementing networking services and other character-based I/O as described in the System 1088 Interfaces volume of IEEE Std. 1003.1-200x, Section 2.6, STREAMS. 1089 It includes the following functions: 1090 fattach( ), fdetach( ), getmsg( ), ioctl( ), isastream( ), putmsg( ), putpmsg( ) | 1091 and the header. 1092 Where applicable, whole pages are marked STREAMS, together with the appropriate option 1093 margin legend for the SYNOPSIS section (see Section 1.5.1 (on page 10)). Where additional 1094 semantics have been added to existing pages, the new material is identified by use of the 1095 appropriate margin legend for the underlying option defined within IEEE Std. 1003.1-200x. 1096 Legacy 1097 The Legacy Option Group is denoted by the symbolic constant _XOPEN_LEGACY. 1098 The Legacy Option Group includes the functions and headers which were mandatory in 1099 previous versions of IEEE Std. 1003.1-200x but are optional in this version. 1100 These functions and headers are retained in IEEE Std. 1003.1-200x because of their widespread 1101 use. Application writers should not rely on the existence of these functions or headers in new 1102 applications, but should follow the migration path detailed in the APPLICATION USAGE 1103 sections of the relevant pages. 1104 Various factors may have contributed to the decision to mark a function or header LEGACY. In 1105 all cases, the specific reasons for the withdrawal of a function or header are documented on the Base Definitions, Issue 6 31 Implementation Conformance Conformance 1106 relevant pages. 1107 Once a function or header is marked LEGACY, no modifications are made to the specifications 1108 of such functions or headers other than to the APPLICATION USAGE sections of the relevant 1109 pages. 1110 The functions and headers which form this Option Group are as follows: 1111 bcmp( ), bcopy( ), bzero( ), ecvt( ), fcvt( ), ftime( ), gcvt( ), getwd( ), index( ), mktemp( ), rindex( ), | 1112 utimes( ) | 1113 An implementation that claims conformance to this Option Group shall set the macro 1114 _XOPEN_LEGACY to a value other than -1. 1115 2.1.6 Options 1116 The following symbolic constants reflect implementation options for IEEE Std. 1003.1-200x. 1117 These symbols can be used by the application to determine which optional facilities are present 1118 on the implementation. The sysconf( ) function defined in the System Interfaces volume of 1119 IEEE Std. 1003.1-200x or the getconf utility defined in the Shell and Utilities volume of | 1120 IEEE Std. 1003.1-200x can be used to retrieve the value of each symbol on each specific | 1121 implementation. 1122 Where an option is not supported, the associated utilities, functions, or facilities need not be 1123 present. 1124 Margin codes are defined for each option (see Section 1.5.1 (on page 10)). 1125 2.1.6.1 System Interfaces 1126 ADV _POSIX_ADVISORY_INFO 1127 If this symbolic constant is defined, then the implementation supports the functions and 1128 additional semantics in the Advisory Information option. 1129 AIO _POSIX_ASYNCHRONOUS_IO 1130 If this symbolic constant is defined, then the implementation supports the functions and 1131 additional semantics in the Asynchronous Input and Output option. 1132 BAR _POSIX_BARRIERS 1133 If this symbolic constant is defined, then the implementation supports the functions and 1134 additional semantics in the Barriers option. 1135 CS _POSIX_CLOCK_SELECTION 1136 If this symbolic constant is defined, then the implementation supports the functions and 1137 additional semantics in the Clock Selection option. 1138 CPT _POSIX_CPUTIME 1139 If this symbolic constant is defined, then the implementation supports the functions and 1140 additional semantics in the Process CPU-Time Clocks option. 1141 FSC _POSIX_FSYNC 1142 If this symbolic constant is defined, then the implementation supports the functions and 1143 additional semantics in the File Synchronization option. 1144 IP6 _POSIX_IPV6 1145 If this symbol is defined, then the implementation supports the functions and additional 1146 semantics in the IPV6 option. 1147 MF _POSIX_MAPPED_FILES 1148 If this symbolic constant is defined, then the implementation supports the functions and 32 Technical Standard (2000) (Draft July 28, 2000) Conformance Implementation Conformance 1149 additional semantics in the Memory Mapped Files option. 1150 ML _POSIX_MEMLOCK 1151 If this symbolic constant is defined, then the implementation supports the functions and 1152 additional semantics in the Process Memory Locking option. 1153 MLR _POSIX_MEMLOCK_RANGE 1154 If this symbolic constant is defined, then the implementation supports the functions and 1155 additional semantics in the Range Memory Locking option. 1156 MPR _POSIX_MEMORY_PROTECTION 1157 If this symbolic constant is defined, then the implementation supports the functions and 1158 additional semantics in the Memory Protection option. 1159 MSG _POSIX_MESSAGE_PASSING 1160 If this symbolic constant is defined, then the implementation supports the functions and 1161 additional semantics in the Message Passing option. 1162 MON _POSIX_MONOTONIC_CLOCK 1163 If this symbolic constant is defined, then the implementation supports the functions and 1164 additional semantics in the Monotonic Clock option. 1165 PIO _POSIX_PRIORITIZED_IO 1166 If this symbolic constant is defined, then the implementation supports the functions and 1167 additional semantics in the Prioritized Input and Output option. 1168 PS _POSIX_PRIORITY_SCHEDULING 1169 If this symbolic constant is defined, then the implementation supports the functions and 1170 additional semantics in the Process Scheduling option. | 1171 RTS _POSIX_REALTIME_SIGNALS 1172 If this symbolic constant is defined, then the implementation supports the functions and 1173 additional semantics in the Realtime Signals Extension option. | 1174 SEM _POSIX_SEMAPHORES 1175 If this symbolic constant is defined, then the implementation supports the functions and 1176 additional semantics in the Semaphores option. 1177 SHM _POSIX_SHARED_MEMORY_OBJECTS 1178 If this symbolic constant is defined, then the implementation supports the functions and 1179 additional semantics in the Shared Memory Objects option. 1180 SH _POSIX_SHELL 1181 If this symbolic constant is defined, then the implementation supports the sh utility | 1182 command line interpretor specified by the Shell and Utilities volume of | 1183 IEEE Std. 1003.1-200x. | 1184 SPN _POSIX_SPAWN 1185 If this symbolic constant is defined, then the implementation supports the functions and 1186 additional semantics in the Spawn option. 1187 SPI _POSIX_SPIN_LOCKS 1188 If this symbolic constant is defined, then the implementation supports the functions and 1189 additional semantics in the Spin Locks option. 1190 SS _POSIX_SPORADIC_SERVER 1191 If this symbolic constant is defined, then the implementation supports the functions and 1192 additional semantics in the Process Sporadic Server option. Base Definitions, Issue 6 33 Implementation Conformance Conformance 1193 SIO _POSIX_SYNCHRONIZED_IO 1194 If this symbolic constant is defined, then the implementation supports the functions and 1195 additional semantics in the Synchronized Input and Output option. 1196 TSA _POSIX_THREAD_ATTR_STACKADDR 1197 If this symbolic constant is defined, then the implementation supports the additional 1198 semantics in the Thread Stack Address Attribute option. 1199 TSS _POSIX_THREAD_ATTR_STACKSIZE 1200 If this symbolic constant is defined, then the implementation supports the additional 1201 semantics in the Thread Stack Address Size option. 1202 TCT _POSIX_THREAD_CPUTIME 1203 If this symbolic constant is defined, then the implementation supports the functions and 1204 additional semantics in the Thread CPU-Time Clocks option. 1205 TPI _POSIX_THREAD_PRIO_INHERIT 1206 If this symbolic constant is defined, then the implementation supports the functions and 1207 additional semantics in the Threads Priority Inheritance option. 1208 TPP _POSIX_THREAD_PRIO_PROTECT 1209 If this symbolic constant is defined, then the implementation supports the additional 1210 semantics in the Thread Priority Protection option. 1211 TPS _POSIX_THREAD_PRIORITY_SCHEDULING 1212 If this symbolic constant is defined, then the implementation supports the functions and 1213 additional semantics in the Thread Execution Scheduling option. 1214 TSH _POSIX_THREAD_PROCESS_SHARED 1215 If this symbolic constant is defined, then the implementation supports the additional 1216 semantics in the Thread Process-Shared Synchronization option. 1217 TSF _POSIX_THREAD_SAFE_FUNCTIONS 1218 If this symbolic constant is defined, then the implementation supports the functions and 1219 additional semantics in the Thread-Safe Functions option. 1220 TSP _POSIX_THREAD_SPORADIC_SERVER 1221 If this symbolic constant is defined, then the implementation supports the functions and 1222 additional semantics in the Thread Sporadic Server option. 1223 THR _POSIX_THREADS 1224 If this symbolic constant is defined, then the implementation supports the functions and 1225 additional semantics in the Threads option. 1226 TMO _POSIX_TIMEOUTS 1227 If this symbolic constant is defined, then the implementation supports the functions and 1228 additional semantics in the Timeouts option. 1229 TMR _POSIX_TIMERS 1230 If this symbolic constant is defined, then the implementation supports the functions and 1231 additional semantics in the Timers option. | 1232 TRC _POSIX_TRACE | 1233 If this symbolic constant is defined, then the implementation supports the functions and | 1234 additional semantics in the Trace option. | 1235 TEF _POSIX_TRACE_EVENT_FILTER | 1236 If this symbolic constant is defined, then the implementation supports the functions and | 1237 additional semantics in the Trace Event Filter option. | 34 Technical Standard (2000) (Draft July 28, 2000) Conformance Implementation Conformance 1238 TRL _POSIX_TRACE_LOG | 1239 If this symbolic constant is defined, then the implementation supports the functions and | 1240 additional semantics in the Trace Log option. | 1241 TRI _POSIX_TRACE_INHERIT | 1242 If this symbolic constant is defined, then the implementation supports the functions and | 1243 additional semantics in the Trace Inherit option. | 1244 TYM _POSIX_TYPED_MEMORY_OBJECTS 1245 If this symbolic constant is defined, then the implementation supports the functions and 1246 additional semantics in the Typed Memory Objects option. 1247 2.1.6.2 Shell and Utilities 1248 Each of these symbols shall be considered valid names by the implementation. Each shall be 1249 defined on the system with a value of 1 if the corresponding option is supported; otherwise, the 1250 symbol shall be undefined. 1251 The literal names shown below apply only to the getconf utility. 1252 CD POSIX2_C_DEV 1253 The system supports the C-Language Development Utilities option. 1254 The utilities in the C-Language Development Utilities option are used for the development 1255 of C-language applications, including compilation or translation of C source code and 1256 complex program generators for simple lexical tasks and processing of context-free 1257 grammars. 1258 The utilities listed below may be provided by a conforming system; however, any system 1259 claiming conformance to the C-Language Development Utilities option shall provide all of 1260 the utilities listed. 1261 c99 | 1262 lex | 1263 yacc | 1264 POSIX2_CHAR_TERM 1265 The system supports the Terminal Characteristics option. This value need not be present on 1266 a system not supporting the User Portability Utilities option. 1267 Where applicable, the dependency is noted within the description of the utility. 1268 This option applies only to systems supporting the User Portability Utilities option. If 1269 supported, then the system supports at least one terminal type capable of all operations 1270 described in IEEE Std. 1003.1-200x; see Section 10.2 (on page 211). 1271 FD POSIX2_FORT_DEV 1272 The system supports the FORTRAN Development Utilities option. 1273 The fort77 FORTRAN compiler is the only utility in the FORTRAN Development Utilities 1274 option. This is used for the development of FORTRAN language applications, including 1275 compilation or translation of FORTRAN source code. 1276 The fort77 utility may be provided by a conforming system; however, any system claiming 1277 conformance to the FORTRAN Development Utilities option shall provide the fort77 utility. 1278 FR POSIX2_FORT_RUN 1279 The system supports the FORTRAN Runtime Utilities option. Base Definitions, Issue 6 35 Implementation Conformance Conformance 1280 The asa utility is the only utility in the FORTRAN Runtime Utilities option. 1281 The asa utility may be provided by a conforming system; however, any system claiming 1282 conformance to the FORTRAN Runtime Utilities option shall provide the asa utility. 1283 POSIX2_LOCALEDEF 1284 The system supports the Locale Creation Utilities option. 1285 If supported, the system supports the creation of locales as described in the localedef utility. 1286 The localedef utility may be provided by a conforming system; however, any system 1287 claiming conformance to the Locale Creation Utilities option shall provide the localedef 1288 utility. 1289 BE POSIX2_PBS 1290 The system supports the Batch Environment Services and Utilities option (see the Shell and | 1291 Utilities volume of IEEE Std. 1003.1-200x, Chapter 3, Batch Environment Services). | 1292 Note: The Batch Environment Services and Utilities option is a combination of 1293 mandatory and optional batch services and utilities. The POSIX_PBS symbolic 1294 constant implies the system supports all the mandatory batch services and 1295 utilities. 1296 POSIX2_PBS_ACCOUNTING 1297 The system supports the Batch Accounting option. 1298 POSIX2_PBS_CHECKPOINT 1299 The system supports the Batch Checkpoint/Restart option. 1300 POSIX2_PBS_LOCATE 1301 The system supports the Locate Batch Job Request option. 1302 POSIX2_PBS_MESSAGE 1303 The system supports the Batch Job Message Request option. 1304 POSIX2_PBS_TRACK 1305 The system supports the Track Batch Job Request option. 1306 SD POSIX2_SW_DEV 1307 The system supports the Software Development Utilities option. 1308 The utilities in the Software Development Utilities option are used for the development of 1309 applications, including compilation or translation of source code, the creation and 1310 maintenance of library archives, and the maintenance of groups of inter-dependent 1311 programs. 1312 The utilities listed below may be provided by the conforming system; however, any system 1313 claiming conformance to the Software Development Utilities option shall provide all of the 1314 utilities listed here. 1315 ar | 1316 make | 1317 nm | 1318 strip | 1319 UP POSIX2_UPE 1320 The system supports the User Portability Utilities option. 1321 The utilities in the User Portability Utilities option shall be implemented on all systems that 1322 claim conformance to this option. Certain utilities are noted as having features that cannot 1323 be implemented on all terminal types; if the POSIX2_CHAR_TERM option is supported, the 36 Technical Standard (2000) (Draft July 28, 2000) Conformance Implementation Conformance 1324 system shall support all such features on at least one terminal type; see Section 10.2 (on 1325 page 211). 1326 Some of the utilities are required only on systems that also support the Software 1327 Development Utilities option, or the character-at-a-time terminal option (see Section 10.2 1328 (on page 211)); such utilities have this noted in their DESCRIPTION sections. All of the 1329 other utilities listed are required only on systems that claim conformance to the User 1330 Portability Utilities option. 1331 alias expand |nm | unalias | | ||||| 1332 at fc |patch | unexpand | | |||| 1333 batch fg |ps | uudecode | | |||| 1334 bg file |renice | uuencode | | |||| 1335 crontab jobs |split | vi | | |||| 1336 split man |strings | who | | |||| 1337 ctags mesg |tabs | write | | |||| 1338 df more |talk | | ||| 1339 du newgrp |time | | ||| 1340 ex nice |tput | | ||| Base Definitions, Issue 6 37 Application Conformance Conformance 1341 2.2 Application Conformance 1342 All applications claiming conformance to IEEE Std. 1003.1-200x shall use only language- 1343 dependent services for the C programming language described in Section 2.3 (on page 40), shall | 1344 use only the utilities and facilities defined in the Shell and Utilities volume of | 1345 IEEE Std. 1003.1-200x, and shall fall within one of the following categories. | 1346 2.2.1 Strictly Conforming POSIX Application 1347 A Strictly Conforming POSIX Application is an application that requires only the facilities 1348 described in IEEE Std. 1003.1-200x. Such an application: 1349 1. Shall accept any implementation behavior that results from actions it takes in areas 1350 described in IEEE Std. 1003.1-200x as implementation-defined or unspecified, or where | 1351 IEEE Std. 1003.1-200x indicates that implementations may vary 1352 2. Shall not perform any actions that are described as producing undefined results 1353 3. For symbolic constants, shall accept any value in the range permitted by 1354 IEEE Std. 1003.1-200x, but shall not rely on any value in the range being greater than the 1355 minimums listed or being less than the maximums listed in IEEE Std. 1003.1-200x 1356 4. Shall not use facilities designated as obsolescent 1357 5. Is required to tolerate and permitted to adapt to the presence or absence of optional 1358 facilities whose availability is indicated by Section 2.1.3 (on page 20) 1359 6. For the C programming language, shall not produce any output dependent on any 1360 behavior described in the ISO C standard as unspecified, undefined, or implementation- | 1361 defined, unless the System Interfaces volume of IEEE Std. 1003.1-200x specifies the behavior | 1362 7. For the C programming language, shall not exceed any minimum implementation limit 1363 defined in the ISO C standard, unless the System Interfaces volume of 1364 IEEE Std. 1003.1-200x specifies a higher minimum implementation limit 1365 8. For the C programming language, shall define _POSIX_C_SOURCE to be 200xxxL before 1366 any header is included 1367 Within IEEE Std. 1003.1-200x, any restrictions placed upon a Conforming POSIX Application 1368 shall restrict a Strictly Conforming POSIX Application. 1369 2.2.2 Conforming POSIX Application 1370 2.2.2.1 ISO/IEC Conforming POSIX Application 1371 An ISO/IEC Conforming POSIX Application is an application that uses only the facilities 1372 described in IEEE Std. 1003.1-200x and approved Conforming Language bindings for any ISO or 1373 IEC standard. Such an application shall include a statement of conformance that documents all 1374 options and limit dependencies, and all other ISO or IEC standards used. 1375 2.2.2.2 Conforming POSIX Application 1376 A Conforming POSIX Application differs from an ISO/IEC Conforming 1377 POSIX Application in that it also may use specific standards of a single ISO/IEC member body 1378 referred to here as . Such an application shall include a statement of 1379 conformance that documents all options and limit dependencies, and all other 1380 standards used. 38 Technical Standard (2000) (Draft July 28, 2000) Conformance Application Conformance 1381 2.2.3 Conforming POSIX Application Using Extensions 1382 A Conforming POSIX Application Using Extensions is an application that differs from a 1383 Conforming POSIX Application only in that it uses non-standard facilities that are consistent 1384 with IEEE Std. 1003.1-200x. Such an application shall fully document its requirements for these 1385 extended facilities, in addition to the documentation required of a Conforming POSIX 1386 Application. A Conforming POSIX Application Using Extensions shall be either an ISO/IEC 1387 Conforming POSIX Application Using Extensions or a Conforming POSIX 1388 Application Using Extensions (see Section 2.2.2.1 (on page 38) and Section 2.2.2.2 (on page 38)). 1389 2.2.4 Strictly Conforming XSI Application 1390 A Strictly Conforming XSI Application is an application that requires only the facilities described 1391 in IEEE Std. 1003.1-200x. Such an application: 1392 1. Shall accept any implementation behavior that results from actions it takes in areas 1393 described in IEEE Std. 1003.1-200x as implementation-defined or unspecified, or where | 1394 IEEE Std. 1003.1-200x indicates that implementations may vary 1395 2. Shall not perform any actions that are described as producing undefined results 1396 3. For symbolic constants, shall accept any value in the range permitted by 1397 IEEE Std. 1003.1-200x, but shall not rely on any value in the range being greater than the 1398 minimums listed or being less than the maximums listed 1399 4. Shall not use facilities designated as obsolescent 1400 5. Is required to tolerate and permitted to adapt to the presence or absence of optional 1401 facilities whose availability is indicated by Section 2.1.4 (on page 23) 1402 6. For the C programming language, shall not produce any output dependent on any 1403 behavior described in the ISO C standard as unspecified, undefined, or implementation- | 1404 defined, unless the System Interfaces volume of IEEE Std. 1003.1-200x specifies the behavior | 1405 7. For the C programming language, shall not exceed any minimum implementation limit 1406 defined in the ISO C standard, unless the System Interfaces volume of 1407 IEEE Std. 1003.1-200x specifies a higher minimum implementation limit 1408 8. For the C programming language, shall define _XOPEN_SOURCE to be 600 before any 1409 header is included 1410 Within IEEE Std. 1003.1-200x, any restrictions placed upon a Conforming POSIX Application 1411 shall restrict a Strictly Conforming XSI Application. 1412 2.2.5 Conforming XSI Application Using Extensions 1413 A Conforming XSI Application Using Extensions is an application that differs from a Strictly 1414 Conforming XSI Application only in that it uses non-standard facilities that are consistent with 1415 IEEE Std. 1003.1-200x. Such an application shall fully document its requirements for these 1416 extended facilities, in addition to the documentation required of a Strictly Conforming XSI 1417 Application. Base Definitions, Issue 6 39 Language-Dependent Services for the C Programming Language Conformance 1418 2.3 Language-Dependent Services for the C Programming Language 1419 Implementors seeking to claim conformance using the ISO C standard shall claim POSIX 1420 conformance as described in Section 2.1.3 (on page 20), C Language Binding (C Standard 1421 Language-Dependent System Support). 1422 2.4 Other Language-Related Specifications 1423 IEEE Std. 1003.1-200x is currently specified in terms of the shell command language and ISO C. 1424 Bindings to other programming languages are being developed. 1425 If conformance to IEEE Std. 1003.1-200x is claimed for implementation of any programming 1426 language, the implementation of that language shall support the use of external symbols distinct 1427 to at least 31 bytes in length in the source program text. (That is, identifiers that differ at or 1428 before the thirty-first byte shall be distinct.) If a national or international standard governing a 1429 language defines a maximum length that is less than this value, the language-defined maximum 1430 shall be supported. External symbols that differ only by case shall be distinct when the character 1431 set in use distinguishes uppercase and lowercase characters and the language permits (or | 1432 requires) uppercase and lowercase characters to be distinct in external symbols. 40 Technical Standard (2000) (Draft July 28, 2000) Chapter 3 Definitions 1433 1434 3.1 Abortive Release 1435 An abrupt termination of a network connection that may result in the loss of data. 1436 3.2 Absolute Path Name 1437 A path name beginning with a single or more than two slashes; see also Section 3.268 (on page 1438 86). 1439 Note: Path Name Resolution is defined in detail in Section 4.9 (on page 123). 1440 3.3 Access Mode 1441 A particular form of access permitted to a file. 1442 3.4 Additional File Access Control Mechanism 1443 An implementation-defined mechanism that is layered upon the access control mechanisms | 1444 defined here, but which do not grant permissions beyond those defined herein, although they | 1445 may further restrict them. | 1446 Note: File Access Permissions are defined in detail in Section 4.3 (on page 121). 1447 3.5 Address Space 1448 The memory locations that can be referenced by a process or the threads of a process. 1449 3.6 Advisory Information 1450 An interface that advises the implementation on (portable) application behavior so that it can | 1451 optimize the system. | Base Definitions, Issue 6 41 Affirmative Response Definitions 1452 3.7 Affirmative Response 1453 An input string that matches one of the responses acceptable to the LC_MESSAGES category 1454 keyword yesexpr, matching an extended regular expression in the current locale. 1455 Note: The LC_MESSAGES category is defined in detail in Section 7.3.6 (on page 174). 1456 3.8 Alert 1457 To cause the user's terminal to give some audible or visual indication that an error or some other 1458 event has occurred. When the standard output is directed to a terminal device, the method for 1459 alerting the terminal user is unspecified. When the standard output is not directed to a terminal 1460 device, the alert is accomplished by writing the character to standard output (unless the 1461 utility description indicates that the use of standard output produces undefined results in this 1462 case). 1463 3.9 Alert Character () 1464 A character that in the output stream should cause a terminal to alert its user via a visual or 1465 audible notification. The character is the character designated by '\a' in the C | 1466 language. It is unspecified whether this character is the exact sequence transmitted to an output 1467 device by the system to accomplish the alert function. 1468 3.10 Alias Name 1469 In the shell command language, a word consisting solely of underscores, digits, and alphabetics 1470 from the portable character set and any of the following characters: '!', '%', ',', '@'. 1471 Implementations may allow other characters within alias names as an extension. 1472 Note: The Portable Character Set is defined in detail in Section 6.1 (on page 133). 1473 3.11 Alignment 1474 A requirement that objects of a particular type be located on storage boundaries with addresses 1475 that are particular multiples of a byte address 1476 Note: See also the ISO C standard, § B3. 42 Technical Standard (2000) (Draft July 28, 2000) Definitions Alternate File Access Control Mechanism 1477 3.12 Alternate File Access Control Mechanism 1478 An implementation-defined mechanism that is independent of the access control mechanisms | 1479 defined herein, and which if enabled on a file may either restrict or extend the permissions of a | 1480 given user. IEEE Std. 1003.1-200x defines when such mechanisms can be enabled and when they | 1481 are disabled. | 1482 Note: File Access Permissions are defined in detail in Section 4.3 (on page 121). 1483 3.13 Alternate Signal Stack 1484 Memory associated with a thread, established upon request by the implementation for a thread, | 1485 separate from the thread signal stack, in which signal handlers responding to signals sent to that 1486 thread may be executed. | 1487 3.14 Ancillary Data 1488 Protocol-specific, local system-specific, or optional information. The information can be both 1489 local or end-to-end significant, header information, part of a data portion, protocol-specific, and 1490 implementation or system-specific. 1491 3.15 Angle Brackets 1492 The characters '<' (left-angle-bracket) and '>' (right-angle-bracket). When used in the phrase 1493 ``enclosed in angle brackets'', the symbol '<' immediately precedes the object to be enclosed, 1494 and '>' immediately follows it. When describing these characters in the portable character set, 1495 the names and are used. 1496 3.16 Application 1497 A computer program that performs some desired function. 1498 3.17 Application Address 1499 Endpoint address of a specific application. Base Definitions, Issue 6 43 Application Program Interface (API) Definitions 1500 3.18 Application Program Interface (API) 1501 The definition of syntax and semantics for providing computer system services. 1502 3.19 Appropriate Privileges 1503 An implementation-defined means of associating privileges with a process with regard to the | 1504 function calls, function call options, and the commands that need special privileges. There may 1505 be zero or more such means. These means (or lack thereof) are described in the conformance | 1506 document. 1507 Note: Function calls are defined in the System Interfaces volume of IEEE Std. 1003.1-200x, 1508 and commands are defined in the Shell and Utilities volume of IEEE Std. 1003.1-200x. | 1509 3.20 Argument 1510 In the shell command language, a parameter passed to a utility as the equivalent of a single 1511 string in the argv array created by one of the exec functions. An argument is one of the options, 1512 option-arguments, or operands following the command name. 1513 Note: The Utility Argument Syntax is defined in detail in Section 12.1 (on page 227) and the | 1514 Shell and Utilities volume of IEEE Std. 1003.1-200x, Section 2.9.1.1, Command Search | 1515 and Execution. | 1516 In the C language, an expression in a function call expression or a sequence of preprocessing 1517 tokens in a function-like macro invocation. 1518 3.21 Arm (a Timer) 1519 To start a timer measuring the passage of time, enabling notifying a process when the specified | 1520 time or time interval has passed. | 1521 3.22 Assignment 1522 NEW DEF REQUIRED. | 1523 Note: Variable Assignment is defined in detail in Section 4.16 (on page 127). | 44 Technical Standard (2000) (Draft July 28, 2000) Definitions Asterisk 1524 3.23 Asterisk 1525 The character '*'. 1526 3.24 Async-Cancel-Safe Function 1527 A function that may be safely invoked by an application while the asynchronous form of | 1528 cancelation is enabled. No function is async-cancel-safe unless explicitly described as such. | 1529 3.25 Asynchronous Events 1530 Events that occur independently of the execution of the application. 1531 3.26 Asynchronous Input and Output 1532 A functionality enhancement to allow an application process to queue data input and output 1533 commands with asynchronous notification of completion. This facility includes in its scope the 1534 requirements of supercomputer applications. 1535 3.27 Async-Signal-Safe Function 1536 A function that may be invoked, without restriction, from signal-catching functions. No function 1537 is async-signal-safe unless explicitly described as such. 1538 3.28 Asynchronously-Generated Signal 1539 A signal that is not attributable to a specific thread. Examples are signals sent via kill( ), signals | 1540 sent from the keyboard, and signals delivered to process groups. Being asynchronous is a 1541 property of how the signal was generated and not a property of the signal number. All signals 1542 may be generated asynchronously. | 1543 Note: The kill( ) function is defined in detail in the System Interfaces volume of 1544 IEEE Std. 1003.1-200x. Base Definitions, Issue 6 45 Asynchronous I/O Operation Definitions 1545 3.29 Asynchronous I/O Operation 1546 An I/O operation that does not of itself cause the thread requesting the I/O to be blocked from | 1547 further use of the processor. 1548 This implies that the process and the I/O operation may be running concurrently. | 1549 3.30 Asynchronous I/O Completion 1550 For an asynchronous read or write operation, when a corresponding synchronous read or write | 1551 would have completed and when any associated status fields have been updated. | 1552 3.31 Authentication 1553 The process of validating a user or process to verify that the user or process is not a counterfeit. 1554 3.32 Authorization 1555 The process of verifying that a user or process has permission to use a resource in the manner 1556 requested. 1557 To ensure security, the user or process would also need to be authenticated before granting 1558 access. 1559 3.33 Background Job 1560 See Background Process Group in Section 3.35. 1561 3.34 Background Process 1562 A process that is a member of a background process group. 1563 3.35 Background Process Group (or Background Job) 1564 Any process group, other than a foreground process group, that is a member of a session that 1565 has established a connection with a controlling terminal. 46 Technical Standard (2000) (Draft July 28, 2000) Definitions Backquote 1566 3.36 Backquote 1567 The character '`', also known as a grave accent. 1568 3.37 Backslash 1569 The character '\', also known as a reverse solidus. 1570 3.38 Backspace Character () 1571 A character that, in the output stream, should cause printing (or displaying) to occur one column 1572 position previous to the position about to be printed. If the position about to be printed is at the 1573 beginning of the current line, the behavior is unspecified. The character is the | 1574 character designated by '\b' in the C language. It is unspecified whether this character is the | 1575 exact sequence transmitted to an output device by the system to accomplish the backspace 1576 function. The character defined here is not necessarily the ERASE special character. 1577 Note: Special Characters are defined in detail in Section 11.1.9 (on page 217). 1578 3.39 Barrier 1579 A synchronization object that allows multiple threads to synchronize at a particular point in | 1580 their execution. | 1581 3.40 Base Character 1582 One of the set of characters defined in the Latin alphabet. In Western European languages other 1583 than English, these characters are commonly used with diacritical marks (accents, cedilla, and so 1584 on) to extend the range of characters in an alphabet. 1585 3.41 Basename 1586 The final, or only, file name in a path name. Base Definitions, Issue 6 47 Basic Regular Expression (BRE) Definitions 1587 3.42 Basic Regular Expression (BRE) 1588 A regular expression (see Section 3.318 (on page 95)) used by the majority of utilities that select 1589 strings from a set of character strings. 1590 Note: Basic Regular Expressions are described in detail in Section 9.3 (on page 198). 1591 3.43 Batch Access List 1592 A list of user IDs and group IDs of those users and groups authorized to place batch jobs in a | 1593 batch queue. 1594 A batch access list is associated with a batch queue. A batch server uses the batch access list of a 1595 batch queue as one of the criteria in deciding to put a batch job in a batch queue. | 1596 3.44 Batch Administrator 1597 A person who is authorized to use all restricted batch services. | 1598 3.45 Batch Client 1599 A computational entity that utilizes batch services by making requests of batch servers. | 1600 Batch clients often provide the means by which users access batch services, although a batch 1601 server may act as a batch client by virtue of making requests of another batch server. | 1602 3.46 Batch Destination 1603 The batch server in a batch system to which a batch job should be sent for processing. | 1604 Acceptance of a batch job at a batch destination is the responsibility of a receiving batch server. 1605 A batch destination may consist of a batch server-specific portion, a network-wide portion, or 1606 both. The batch server-specific portion is referred to as the batch queue. The network-wide 1607 portion is referred to as a batch server name. | 1608 3.47 Batch Destination Identifier 1609 A string that identifies a specific batch destination. | 1610 A string of characters in the portable character set used to specify a particular batch destination. | 1611 Note: The Portable Character Set is defined in detail in Section 6.1 (on page 133). 48 Technical Standard (2000) (Draft July 28, 2000) Definitions Batch Directive 1612 3.48 Batch Directive 1613 A line from a file that is interpreted by the batch server. The line is usually in the form of a | 1614 comment and is an additional means of passing options to the qsub utility. | 1615 Note: The qsub utility is defined in detail in the Shell and Utilities volume of | 1616 IEEE Std. 1003.1-200x. | 1617 3.49 Batch Job 1618 A set of computational tasks for a computing system. | 1619 Batch jobs are managed by batch servers. 1620 Once created, a batch job may be executing or pending execution. A batch job that is executing 1621 has an associated session leader (a process) that initiates and monitors the computational tasks 1622 of the batch job. | 1623 3.50 Batch Job Attribute 1624 A named data type whose value affects the processing of a batch job. | 1625 The values of the attributes of a batch job affect the processing of that job by the batch server 1626 that manages the batch job. 1627 The attributes defined for a batch job are called the batch job attributes. | 1628 3.51 Batch Job Identifier 1629 A unique name for a batch job. A name that is unique among all other batch job identifiers in a | 1630 batch system and that identifies the batch server to which the batch job was originally 1631 submitted. | 1632 3.52 Batch Job Name 1633 A label that is an attribute of a batch job. The batch job name is not necessarily unique. | Base Definitions, Issue 6 49 Batch Job Owner Definitions 1634 3.53 Batch Job Owner 1635 The username@hostname of the user submitting the batch job, where username is a user name (see | 1636 also Section 3.428 (on page 115)) and hostname is a network host name. | 1637 3.54 Batch Job Priority 1638 An attribute used in selecting a batch job for execution. | 1639 A value specified by the user that may be used by an implementation to determine the order in 1640 which batch jobs are selected to be executed. Job priority has a numeric value in the range -1 024 1641 to 1 023. | 1642 Note: The batch job priority is not the execution priority (nice value) of the batch job. 1643 3.55 Batch Job State 1644 An attribute of a batch job. | 1645 The state of a batch job determines the types of requests that the batch server that manages the 1646 batch job can accept for the batch job. Valid states include QUEUED, RUNNING, HELD, 1647 WAITING, EXITING, and TRANSITING. | 1648 3.56 Batch Name Service 1649 A service that assigns batch names that are unique within the batch name space, and that can | 1650 translate a unique batch name into the location of the named batch entity. | 1651 3.57 Batch Name Space 1652 The environment within which a batch name is known to be unique. | 1653 3.58 Batch Node 1654 A host containing part or all of a batch system. | 1655 A batch node is a host meeting at least one of the following conditions: 1656 * Capable of executing a batch client 1657 * Contains a routing batch queue 1658 * Contains an execution batch queue 50 Technical Standard (2000) (Draft July 28, 2000) Definitions Batch Operator 1659 3.59 Batch Operator 1660 A person who is authorized to use some, but not all, restricted batch services. | 1661 3.60 Batch Queue 1662 A manageable object that represents a set of batch jobs and is managed by a single batch server. | 1663 Note: Each batch job managed by a batch server is a member of a single batch queue 1664 managed by that server. 1665 Such a set of batch jobs is called a batch queue largely for historical reasons. Jobs are 1666 selected from the batch queue for execution based on attributes such as priority, 1667 resource requirements, and hold conditions. 1668 Two types of batch queue are described in IEEE Std. 1003.1-200x: routing batch queues 1669 and execution batch queues. 1670 3.61 Batch Queue Attribute 1671 A named data type whose value affects the processing of all batch jobs that are members of the | 1672 batch queue. 1673 A batch queue has attributes that affect the processing of batch jobs that are members of the 1674 batch queue. 1675 The attributes defined for a batch queue are called the batch batch queue attributes. | 1676 3.62 Batch Queue Position 1677 The place a batch job occupies in a batch queue. | 1678 This place is relative to other batch jobs in the batch queue and defined in part by submission 1679 time and its priority; see also Section 3.63. | 1680 3.63 Batch Queue Priority 1681 The maximum job priority allowed for any batch job in a given batch queue. | 1682 The batch queue priority is set and may be changed by users with appropriate privilege. The | 1683 priority is bounded in an implementation-defined manner. | Base Definitions, Issue 6 51 Batch Rerunability Definitions 1684 3.64 Batch Rerunability 1685 An attribute of a batch job. | 1686 If a batch job may be rerun from the beginning after an abnormal termination without affecting 1687 the validity of the results, the batch job is said to be rerunable. | 1688 3.65 Batch Restart 1689 Resume the processing of a batch job from the point of the last checkpoint. Typically, this is done | 1690 if the batch job has been interrupted because of a system failure. | 1691 3.66 Batch Server 1692 A computational entity that provides batch services. | 1693 3.67 Batch Server Name 1694 A string that identifies a specific server in a network. | 1695 A string of characters in the portable character set used to specify a particular server in a 1696 network. | 1697 Note: The Portable Character Set is defined in detail in Section 6.1 (on page 133). 1698 3.68 Batch Service 1699 Computational and organizational services performed by a batch system on behalf of batch jobs. | 1700 Batch services are of two types: requested and deferred. | 1701 Note: Batch Services are listed in the Shell and Utilities volume of IEEE Std. 1003.1-200x, | 1702 Table 3-5, Batch Services Summary. | 1703 3.69 Batch Service Request 1704 A solicitation of services from a batch client to a batch server. | 1705 A batch service request may entail the exchange of any number of messages between the batch 1706 client and the batch server. 1707 When naming specific types of service requests, the term request is qualified by the type of | 1708 request, as in Queue Batch Job Request and Delete Batch Job Request. | 52 Technical Standard (2000) (Draft July 28, 2000) Definitions Batch Submission 1709 3.70 Batch Submission 1710 The process by which a batch client requests that a batch server create a batch job via a Queue Job | 1711 Request to perform a specified computational task. | 1712 3.71 Batch System 1713 A collection of one or more batch servers. | 1714 3.72 Batch Target User 1715 The name of a user on the batch destination batch server. | 1716 The target user is the user name under whose account the batch job is to execute on the 1717 destination batch server. | 1718 3.73 Batch User 1719 A person who is authorized to make use of batch services. | 1720 3.74 Bind 1721 Assign a network address to an endpoint. 1722 3.75 Blank Character () 1723 One of the characters that belong to the blank character class as defined via the LC_CTYPE 1724 category in the current locale. In the POSIX locale, a character is either a or a 1725 character. 1726 3.76 Blank Line 1727 A line consisting solely of zero or more characters terminated by a character; 1728 see also Section 3.146 (on page 66). Base Definitions, Issue 6 53 Blocked Process (or Thread) Definitions 1729 3.77 Blocked Process (or Thread) 1730 A process (or thread) that is waiting for some condition (other than the availability of a | 1731 processor) to be satisfied before it can continue execution. 1732 3.78 Blocking 1733 Executing with O_NONBLOCK not set; see also Section 3.242 (on page 82). 1734 3.79 Block-Mode Terminal 1735 A terminal device operating in a mode incapable of the character-at-a-time input and output 1736 operations described by some of the standard utilities. 1737 Note: Output Devices and Terminal Types are defined in detail in Section 10.2 (on page 1738 211). 1739 3.80 Block Special File 1740 A file that refers to a device. A block special file is normally distinguished from a character 1741 special file by providing access to the device in a manner such that the hardware characteristics 1742 of the device are not visible. 1743 3.81 Braces 1744 The characters '{' (left brace) and '}' (right brace), also known as curly braces. When used in 1745 the phrase ``enclosed in (curly) braces'' the symbol '{' immediately precedes the object to be | 1746 enclosed, and '}' immediately follows it. When describing these characters in the portable | 1747 character set, the names and are used. 1748 3.82 Brackets 1749 The characters '[' (left-bracket) and ']' (right-bracket), also known as square brackets. When 1750 used in the phrase ``enclosed in (square) brackets'' the symbol '[' immediately precedes the | 1751 object to be enclosed, and ']' immediately follows it. When describing these characters in the | 1752 portable character set, the names and are used. 54 Technical Standard (2000) (Draft July 28, 2000) Definitions Break Value 1753 3.83 Break Value 1754 The address at which dynamic memory allocation starts. | 1755 3.84 Broadcast 1756 The transfer of data from one endpoint to several endpoints, as described in RFC 919 and 1757 RFC 922. 1758 3.85 Built-In Utility (or Built-In) 1759 A utility implemented within a shell. The utilities referred to as special built-ins have special 1760 qualities. Unless qualified, the term built-in includes the special built-in utilities. Regular built-ins | 1761 are not required to be actually built into the shell on the implementation, but they do have 1762 special command-search qualities. 1763 Note: Special Built-In Utilities are defined in detail in the Shell and Utilities volume of | 1764 IEEE Std. 1003.1-200x, Section 2.15, Special Built-In Utilities. | 1765 Regular Built-In Utilities are defined in detail in the Shell and Utilities volume of | 1766 IEEE Std. 1003.1-200x, Section 2.9.1.1, Command Search and Execution. | 1767 3.86 Byte 1768 An individually addressable unit of data storage that is equal to or larger than an octet, used to 1769 store a character or a portion of a character; see also Section 3.89 (on page 56). A byte is 1770 composed of a contiguous sequence of bits, the number of which is implementation-defined. The | 1771 least significant bit is called the low-order bit; the most significant is called the high-order bit. | 1772 Note: The definition of byte is actually from the ISO C standard. It has been reworded 1773 slightly to clarify its intent without introducing the ISO C standard terminology 1774 ``basic execution character set'', which is inapplicable to IEEE Std. 1003.1-200x. It 1775 deviates intentionally from the usage of byte in some international standards, where 1776 it is used as a synonym for octet (always eight bits). A byte may be larger than eight | 1777 bits so that it can be an integral portion of larger data objects that are not evenly | 1778 divisible by eight bits (such as a 36-bit word that contains four 9-bit bytes). | Base Definitions, Issue 6 55 Byte Input/Output Functions Definitions 1779 3.87 Byte Input/Output Functions 1780 The functions that perform byte-oriented input from streams or byte-oriented output to streams: 1781 fgetc( ), fgets( ), fprintf( ), fputc( ), fputs( ), fread( ), fscanf( ), fwrite( ), getc( ), getchar( ), gets( ), printf( ), 1782 putc( ), putchar( ), puts( ), scanf( ), ungetc( ), vfprintf( ), and vprintf( ). 1783 Note: Functions are defined in detail in the System Interfaces volume of 1784 IEEE Std. 1003.1-200x. 1785 3.88 Carriage-Return Character () 1786 A character that in the output stream indicates that printing should start at the beginning of the | 1787 same physical line in which the character occurred. The | 1788 character is the character designated by '\r' in the C language. It is unspecified whether this | 1789 character is the exact sequence transmitted to an output device by the system to accomplish the 1790 movement to the beginning of the line. 1791 3.89 Character 1792 A sequence of one or more bytes representing a single graphic symbol or control code. 1793 Note: This term corresponds to the ISO C standard term multi-byte character, where a | 1794 single-byte character is a special case of a multi-byte character. Unlike the usage in 1795 the ISO C standard, character here has no necessary relationship with storage space, 1796 and byte is used when storage space is discussed. 1797 See the definition of the Portable Character Set in Section 6.1 (on page 133) for a 1798 further explanation of the graphical representations of characters, or glyphs, as 1799 opposed to character encodings. 1800 3.90 Character Array 1801 An array of elements of type char. 1802 3.91 Character Class 1803 A named set of characters sharing an attribute associated with the name of the class. The classes 1804 and the characters that they contain are dependent on the value of the LC_CTYPE category in the 1805 current locale. 1806 Note: The LC_CTYPE category is defined in detail in Section 7.3.1 (on page 147). 56 Technical Standard (2000) (Draft July 28, 2000) Definitions Character Set 1807 3.92 Character Set 1808 A finite set of different characters used for the representation, organization, or control of data. 1809 3.93 Character Special File 1810 A file that refers to a device. One specific type of character special file is a terminal device file. 1811 Note: The General Terminal Interface is defined in detail in Chapter 11 (on page 213). 1812 3.94 Character String 1813 A contiguous sequence of characters terminated by and including the first null byte. 1814 3.95 Child Process 1815 A new process created (by fork( ) or spawn( )) by a given process. A child process remains the 1816 child of the creating process as long as both processes continue to exist. 1817 Note: The fork( ) and spawn( ) functions are defined in detail in the System Interfaces 1818 volume of IEEE Std. 1003.1-200x. 1819 3.96 Circumflex 1820 The character ' '. 1821 3.97 Clock 1822 A software or hardware object that can be used to measure the apparent or actual passage of | 1823 time. 1824 The current value of the time measured by a clock can be queried and, possibly, set to a value 1825 within the legal range of the clock. | 1826 3.98 Clock Jump 1827 The difference between two successive distinct values of a clock, as observed from the | 1828 application via one of the ``get time'' operations. | Base Definitions, Issue 6 57 Clock Tick Definitions 1829 3.99 Clock Tick 1830 An interval of time; an implementation-defined number of these occur each second. Clock ticks | 1831 are one of the units that may be used to express a value found in type clock_t. 1832 3.100 Coded Character Set 1833 A set of unambiguous rules that establishes a character set and the one-to-one relationship 1834 between each character of the set and its bit representation. 1835 3.101 Codeset 1836 The result of applying rules that map a numeric code value to each element of a character set. An 1837 element of a character set may be related to more than one numeric code value but the reverse is 1838 not true. However, for state-dependent encodings the relationship between numeric code values 1839 to elements of a character set may be further controlled by state information. The character set 1840 may contain fewer elements than the total number of possible numeric code values; that is, some 1841 code values may be unassigned. 1842 Note: Character Encoding is defined in detail in Section 6.2 (on page 136). 1843 3.102 Collating Element 1844 The smallest entity used to determine the logical ordering of character or wide-character strings; 1845 see also Section 3.105 (on page 59). A collating element consists of either a single character, or | 1846 two or more characters collating as a single entity. The value of the LC_COLLATE category in the | 1847 current locale determines the current set of collating elements. 1848 3.103 Collating Element Order 1849 The relative order of collating elements as determined by the setting of the LC_COLLATE 1850 category in the current locale. 1851 The collating element order is used in range expressions in REs and is determined by the order in 1852 which collating elements are specified between order_start and order_end keywords in the 1853 LC_COLLATE category. 58 Technical Standard (2000) (Draft July 28, 2000) Definitions Collation 1854 3.104 Collation 1855 The logical ordering of character or wide-character strings according to defined precedence 1856 rules. These rules identify a collation sequence between the collating elements, and such 1857 additional rules that can be used to order strings consisting of multiple collating elements. 1858 3.105 Collation Sequence 1859 The relative order of collating elements as determined by the setting of the LC_COLLATE 1860 category in the current locale. The collation sequence is used for sorting and is determined from 1861 the collating weights assigned to each collating element. In the absence of weights, the collation 1862 sequence is also the collating element order. 1863 Multi-level sorting is accomplished by assigning elements one or more collation weights, up to 1864 the limit {COLL_WEIGHTS_MAX}. On each level, elements may be given the same weight (at 1865 the primary level, called an equivalence class; see also Section 3.152 (on page 66)) or be omitted 1866 from the sequence. Strings that collate equal using the first assigned weight (primary ordering) 1867 are then compared using the next assigned weight (secondary ordering), and so on. 1868 Note: {COLL_WEIGHTS_MAX} is defined in detail in . 1869 3.106 Column Position 1870 A unit of horizontal measure related to characters in a line. 1871 It is assumed that each character in a character set has an intrinsic column width independent of 1872 any output device. Each printable character in the portable character set has a column width of 1873 one. The standard utilities, when used as described in IEEE Std. 1003.1-200x, assume that all 1874 characters have integral column widths. The column width of a character is not necessarily 1875 related to the internal representation of the character (numbers of bits or bytes). 1876 The column position of a character in a line is defined as one plus the sum of the column widths 1877 of the preceding characters in the line. Column positions are numbered starting from 1. 1878 3.107 Command 1879 A directive to the shell to perform a particular task. 1880 Note: Shell Commands are defined in detail in the Shell and Utilities volume of | 1881 IEEE Std. 1003.1-200x, Section 2.9, Shell Commands. | Base Definitions, Issue 6 59 Command Language Interpreter Definitions 1882 3.108 Command Language Interpreter 1883 An interface that interprets sequences of text input as commands. It may operate on an input 1884 stream or it may interactively prompt and read commands from a terminal. It is possible for 1885 applications to invoke utilities through a number of interfaces, which are collectively considered 1886 to act as command interpreters. The most obvious of these are the sh utility and the system( ) 1887 function, although popen( ) and the various forms of exec may also be considered to behave as 1888 interpreters. 1889 Note: The sh utility is defined in detail in the Shell and Utilities volume of | 1890 IEEE Std. 1003.1-200x. | 1891 The system( ), popen( ), and exec functions are defined in detail in the System Interfaces 1892 volume of IEEE Std. 1003.1-200x. 1893 3.109 Composite Graphic Symbol 1894 A graphic symbol consisting of a combination of two or more other graphic symbols in a single 1895 character position, such as a diacritical mark and a base character. 1896 3.110 Condition Variable 1897 A synchronization object which allows a thread to suspend execution, repeatedly, until some | 1898 associated predicate becomes true. A thread whose execution is suspended on a condition 1899 variable is said to be blocked on the condition variable. | 1900 3.111 Connection 1901 An association established between two or more endpoints for the transfer of data | 1902 3.112 Connection Mode 1903 The transfer of data in the context of a connection; see also Section 3.113. 1904 3.113 Connectionless Mode 1905 The transfer of data other than in the context of a connection; see also Section 3.112 and Section 1906 3.126 (on page 62). 60 Technical Standard (2000) (Draft July 28, 2000) Definitions Control Character 1907 3.114 Control Character 1908 A character, other than a graphic character, that affects the recording, processing, transmission, 1909 or interpretation of text. 1910 3.115 Control Operator 1911 In the shell command language, a token that performs a control function. It is one of the 1912 following symbols: 1913 & && ( ) ; ;; newline | || | 1914 The end-of-input indicator used internally by the shell is also considered a control operator. 1915 Note: Token Recognition is defined in detail in the Shell and Utilities volume of | 1916 IEEE Std. 1003.1-200x, Section 2.3, Token Recognition. | 1917 3.116 Controlling Process 1918 The session leader that established the connection to the controlling terminal. If the terminal 1919 subsequently ceases to be a controlling terminal for this session, the session leader ceases to be | 1920 the controlling process. | 1921 3.117 Controlling Terminal 1922 A terminal that is associated with a session. Each session may have at most one controlling 1923 terminal associated with it, and a controlling terminal is associated with exactly one session. 1924 Certain input sequences from the controlling terminal cause signals to be sent to all processes in 1925 the process group associated with the controlling terminal. 1926 Note: The General Terminal Interface is defined in detail in Chapter 11 (on page 213). 1927 3.118 Conversion Descriptor 1928 A per-process unique value used to identify an open codeset conversion. | 1929 3.119 Core File 1930 A file of unspecified format that may be generated when a process terminates abnormally. | Base Definitions, Issue 6 61 CPU Time (Execution Time) Definitions 1931 3.120 CPU Time (Execution Time) 1932 The time spent executing a process or thread, including the time spent executing system services | 1933 on behalf of that process or thread. If the Threads option is supported, then the value of the 1934 CPU-time clock for a process is implementation-defined. With this definition the sum of all the | 1935 execution times of all the threads in a process might not equal the process execution time, even | 1936 in a single-threaded process, because implementations may differ in how they account for time | 1937 during context switches or for other reasons. | 1938 3.121 CPU-Time Clock 1939 A clock that measures the execution time of a particular process or thread. | 1940 3.122 CPU-Time Timer 1941 A timer attached to a CPU-time clock. | 1942 3.123 Current Job | 1943 In the context of job control, the job that will be used as the default for the fg or bg utilities. There | 1944 is at most one current job; see also Section 3.205 (on page 76). | 1945 3.124 Current Working Directory 1946 See Working Directory in Section 3.438 (on page 117). 1947 3.125 Cursor Position 1948 The line and column position on the screen denoted by the terminal's cursor. 1949 3.126 Datagram 1950 A unit of data transferred from one endpoint to another in connectionless mode service. 62 Technical Standard (2000) (Draft July 28, 2000) Definitions Data Segment 1951 3.127 Data Segment 1952 Memory associated with a process, that can contain dynamically allocated data. | 1953 3.128 Deferred Batch Service 1954 A service that is performed as a result of events that are asynchronous with respect to requests. | 1955 Note: Once a batch job has been created, it is subject to deferred services. 1956 3.129 Device 1957 A computer peripheral or an object that appears to the application as such. 1958 3.130 Device ID 1959 A non-negative integer used to identify a device. | 1960 3.131 Directory 1961 A file that contains directory entries. No two directory entries in the same directory have the | 1962 same name. | 1963 3.132 Directory Entry (or Link) 1964 An object that associates a file name with a file. Several directory entries can associate names 1965 with the same file. 1966 3.133 Directory Stream 1967 A sequence of all the directory entries in a particular directory. An open directory stream may be 1968 implemented using a file descriptor. Base Definitions, Issue 6 63 Disarm (a Timer) Definitions 1969 3.134 Disarm (a Timer) 1970 To stop a timer from measuring the passage of time, disabling any future process notifications 1971 (until the timer is armed again). 1972 3.135 Display 1973 To output to the user's terminal. If the output is not directed to a terminal, the results are 1974 undefined. | 1975 3.136 Dollar Sign 1976 The character '$'. 1977 3.137 Dot 1978 In the context of naming files, the file name consisting of a single dot character ('.'). 1979 Note: In the context of shell special built-in utilities, see dot in the Shell and Utilities volume | 1980 of IEEE Std. 1003.1-200x, Section 2.15, Special Built-In Utilities. | 1981 Path Name Resolution is defined in detail in Section 4.9 (on page 123). 1982 3.138 Dot-Dot 1983 The file name consisting solely of two dot characters (".."). 1984 Note: Path Name Resolution is defined in detail in Section 4.9 (on page 123). 1985 3.139 Double-Quote 1986 The character '"', also known as quotation-mark. 1987 Note: The double adjective in this term refers to the two strokes in the character glyph. | 1988 IEEE Std. 1003.1-200x never uses the term double-quote to refer to two apostrophes | 1989 or quotation marks. 64 Technical Standard (2000) (Draft July 28, 2000) Definitions Downshifting 1990 3.140 Downshifting 1991 The conversion of an uppercase character that has a single-character lowercase representation 1992 into this lowercase representation. 1993 3.141 Driver 1994 A module that controls data transferred to and received from devices. | 1995 Note: Drivers are traditionally written to be a part of the system implementation, although | 1996 they are frequently written separately from the writing of the implementation. A 1997 driver may contain processor-specific code, and therefore be non-portable. | 1998 3.142 Effective Group ID 1999 An attribute of a process that is used in determining various permissions, including file access | 2000 permissions; see also Section 3.190 (on page 73). | 2001 3.143 Effective User ID 2002 An attribute of a process that is used in determining various permissions, including file access 2003 permissions; see also Section 3.427 (on page 115). 2004 3.144 Eight-Bit Transparency 2005 The ability of a software component to process 8-bit characters without modifying or utilizing 2006 any part of the character in a way that is inconsistent with the rules of the current coded 2007 character set. 2008 3.145 Empty Directory 2009 A directory that contains, at most, directory entries for dot and dot-dot, and has exactly one link 2010 to it in dot-dot. No other links to the directory may exist. It is unspecified whether an 2011 implementation can ever consider the root directory to be empty. Base Definitions, Issue 6 65 Empty Line Definitions 2012 3.146 Empty Line 2013 A line consisting of only a character; see also Section 3.76 (on page 53). 2014 3.147 Empty String (or Null String) 2015 A string whose first byte is a null byte. 2016 3.148 Empty Wide-Character String 2017 A wide-character string whose first element is a null wide-character code. 2018 3.149 Encoding Rule 2019 The rules used to convert between wide-character codes and multi-byte character codes. 2020 Note: Stream Orientation and Encoding Rules are defined in detail in the System Interfaces 2021 volume of IEEE Std. 1003.1-200x, Section 2.5.2, Stream Orientation and Encoding 2022 Rules. 2023 3.150 Entire Regular Expression 2024 The concatenated set of one or more BREs or EREs that make up the pattern specified for string 2025 selection. 2026 Note: Regular Expressions are defined in detail in Chapter 9 (on page 195). 2027 3.151 Epoch 2028 The time zero hours, zero minutes, zero seconds, on January 1, 1970 Coordinated Universal | 2029 Time. | 2030 Note: See also Seconds Since the Epoch defined in Section 4.12 (on page 125). | 2031 3.152 Equivalence Class 2032 A set of collating elements with the same primary collation weight. 2033 Elements in an equivalence class are typically elements that naturally group together, such as all 2034 accented letters based on the same base letter. 2035 The collation order of elements within an equivalence class is determined by the weights 2036 assigned on any subsequent levels after the primary weight. 66 Technical Standard (2000) (Draft July 28, 2000) Definitions Era 2037 3.153 Era 2038 An alternative method for counting and displaying years. 2039 Note: The LC_TIME category is defined in detail in Section 7.3.5 (on page 168). 2040 3.154 Event Management 2041 The mechanism that enables applications to register for and be made aware of external events 2042 such as data becoming available for reading. 2043 3.155 Executable File 2044 A regular file acceptable as a new process image file by the equivalent of the exec family of 2045 functions, and thus usable as one form of a utility. The standard utilities described as compilers 2046 can produce executable files, but other unspecified methods of producing executable files may 2047 also be provided. The internal format of an executable file is unspecified, but a conforming 2048 application cannot assume an executable file is a text file. 2049 3.156 Execute 2050 In the Shell and Utilities volume of IEEE Std. 1003.1-200x, to perform command search and | 2051 execution actions; see also Section 3.202 (on page 75). | 2052 Note: Command Search and Execution is defined in detail in the Shell and Utilities volume | 2053 of IEEE Std. 1003.1-200x, Section 2.9.1.1, Command Search and Execution. | 2054 3.157 Execution Time 2055 See CPU Time in Section 3.120 (on page 62). 2056 3.158 Execution Time Monitoring 2057 A set of execution time monitoring primitives that allow online measuring of thread and process | 2058 execution times. | Base Definitions, Issue 6 67 Expand Definitions 2059 3.159 Expand 2060 In the shell command language, when not qualified, the act of applying word expansions. 2061 Note: Work Expansions are defined in detail in the Shell and Utilities volume of | 2062 IEEE Std. 1003.1-200x, Section 2.6, Word Expansions. | 2063 3.160 Extended Regular Expression (ERE) 2064 A regular expression (see also Section 3.318 (on page 95)) that is an alternative to the Basic 2065 Regular Expression using a more extensive syntax, occasionally used by some utilities. 2066 Note: Extended Regular Expressions are described in detail in Section 9.4 (on page 203). 2067 3.161 Extended Security Controls 2068 Implementation-defined security controls allowed by the file access permission and appropriate | 2069 privilege (see also Section 3.19 (on page 44)) mechanisms, through which an implementation can 2070 support different security policies from those described in IEEE Std. 1003.1-200x. 2071 Note: See also Extended Security Controls defined in Section 4.2 (on page 121). | 2072 File Access Permissions are defined in detail in Section 4.3 (on page 121). | 2073 3.162 Feature Test Macro 2074 A macro used to determine whether a particular set of features is included from a header. 2075 Note: See also the System Interfaces volume of IEEE Std. 1003.1-200x, Section 2.2, The 2076 Compilation Environment. 2077 3.163 Field 2078 In the shell command language, a unit of text that is the result of parameter expansion, 2079 arithmetic expansion, command substitution, or field splitting. During command processing, the 2080 resulting fields are used as the command name and its arguments. 2081 Note: Parameter Expansion is defined in detail in the Shell and Utilities volume of | 2082 IEEE Std. 1003.1-200x, Section 2.6.2, Parameter Expansion. | 2083 Arithmetic Expansion is defined in detail in the Shell and Utilities volume of | 2084 IEEE Std. 1003.1-200x, Section 2.6.4, Arithmetic Expansion. | 2085 Command Substitution is defined in detail in the Shell and Utilities volume of | 2086 IEEE Std. 1003.1-200x, Section 2.6.3, Command Substitution. | 2087 Field Splitting is defined in detail in the Shell and Utilities volume of | 2088 IEEE Std. 1003.1-200x, Section 2.6.5, Field Splitting. | 2089 For further information on command processing, see the Shell and Utilities volume of | 2090 IEEE Std. 1003.1-200x, Section 2.9.1, Simple Commands. | 68 Technical Standard (2000) (Draft July 28, 2000) Definitions FIFO Special File (or FIFO) 2091 3.164 FIFO Special File (or FIFO) 2092 A type of file with the property that data written to such a file is read on a first-in-first-out basis. 2093 Note: Other characteristics of FIFOs are described in the System Interfaces volume of 2094 IEEE Std. 1003.1-200x, lseek( ), open( ), read( ), and write( ). 2095 3.165 File 2096 An object that can be written to, or read from, or both. A file has certain attributes, including 2097 access permissions and type. File types include regular file, character special file, block special 2098 file, FIFO special file, symbolic link, socket, and directory. Other types of files may be supported 2099 by the implementation. 2100 3.166 File Description 2101 See Open File Description in Section 3.255 (on page 84). 2102 3.167 File Descriptor 2103 A per-process unique, non-negative integer used to identify an open file for the purpose of file 2104 access. The value of a file descriptor is from zero to {OPEN_MAX}. A process can have no more 2105 than {OPEN_MAX} file descriptors open simultaneously. File descriptors may also be used to | 2106 implement message catalog descriptors and directory streams; see also Section 3.255 (on page | 2107 84). 2108 Note: {OPEN_MAX} is defined in detail in . 2109 3.168 File Group Class 2110 The property of a file indicating access permissions for a process related to the group 2111 identification of a process. A process is in the file group class of a file if the process is not in the 2112 file owner class and if the effective group ID or one of the supplementary group IDs of the 2113 process matches the group ID associated with the file. Other members of the class may be | 2114 implementation-defined. | Base Definitions, Issue 6 69 File Mode Definitions 2115 3.169 File Mode 2116 An object containing the file mode bits and file type of a file. 2117 Note: File mode bits and file types are defined in detail in . 2118 3.170 File Mode Bits 2119 A file's file permission bits, set-user-ID-on-execution bit (S_ISUID), and set-group-ID-on- 2120 execution bit (S_ISGID). 2121 Note: File Mode Bits are defined in detail in . 2122 3.171 File Name 2123 A name consisting of 1 to {NAME_MAX} bytes used to name a file. The characters composing 2124 the name may be selected from the set of all character values excluding the slash character and 2125 the null byte. The file names dot and dot-dot have special meaning. A file name is sometimes 2126 referred to as a path name component. 2127 Note: Path Name Resolution is defined in detail in Section 4.9 (on page 123). 2128 3.172 File Name Portability 2129 File names should be constructed from the portable file name character set because the use of 2130 other characters can be confusing or ambiguous in certain contexts. (For example, the use of a 2131 colon (':') in a path name could cause ambiguity if that path name were included in a PATH 2132 definition.) 2133 3.173 File Offset 2134 The byte position in the file where the next I/O operation begins. Each open file description 2135 associated with a regular file, block special file, or directory has a file offset. A character special 2136 file that does not refer to a terminal device may have a file offset. There is no file offset specified 2137 for a pipe or FIFO. 70 Technical Standard (2000) (Draft July 28, 2000) Definitions File Other Class 2138 3.174 File Other Class 2139 The property of a file indicating access permissions for a process related to the user and group 2140 identification of a process. A process is in the file other class of a file if the process is not in the 2141 file owner class or file group class. 2142 3.175 File Owner Class 2143 The property of a file indicating access permissions for a process related to the user 2144 identification of a process. A process is in the file owner class of a file if the effective user ID of 2145 the process matches the user ID of the file. 2146 3.176 File Permission Bits 2147 Information about a file that is used, along with other information, to determine whether a 2148 process has read, write, or execute/search permission to a file. The bits are divided into three 2149 parts: owner, group, and other. Each part is used with the corresponding file class of processes. 2150 These bits are contained in the file mode. 2151 Note: File modes are defined in detail in . 2152 File Access Permissions are defined in detail in Section 4.3 (on page 121). 2153 3.177 File Serial Number 2154 A per-file system unique identifier for a file. 2155 3.178 File System 2156 A collection of files and certain of their attributes. It provides a name space for file serial 2157 numbers referring to those files. 2158 3.179 File Type 2159 See File in Section 3.165 (on page 69). Base Definitions, Issue 6 71 Filter Definitions 2160 3.180 Filter 2161 A command whose operation consists of reading data from standard input or a list of input files 2162 and writing data to standard output. Typically, its function is to perform some transformation 2163 on the data stream. 2164 3.181 First Open (of a File) 2165 When a process opens a file that is not currently an open file within any process. 2166 3.182 Flow Control 2167 The mechanism employed by a communications provider that constrains a sending entity to 2168 wait until the receiving entities can safely receive additional data without loss. 2169 3.183 Foreground Job 2170 See Foreground Process Group in Section 3.185. 2171 3.184 Foreground Process 2172 A process that is a member of a foreground process group. 2173 3.185 Foreground Process Group (or Foreground Job) 2174 A process group whose member processes have certain privileges, denied to processes in 2175 background process groups, when accessing their controlling terminal. Each session that has 2176 established a connection with a controlling terminal has at most one process group of the session 2177 as the foreground process group of that controlling terminal. 2178 Note: The General Terminal Interface is defined in detail in Chapter 11. 2179 3.186 Foreground Process Group ID 2180 The process group ID of the foreground process group. 72 Technical Standard (2000) (Draft July 28, 2000) Definitions Form-Feed Character () 2181 3.187 Form-Feed Character () 2182 A character that in the output stream indicates that printing should start on the next page of an | 2183 output device. The character is the character designated by '\f' in the C language. | 2184 If the character is not the first character of an output line, the result is unspecified. 2185 It is unspecified whether this character is the exact sequence transmitted to an output device by 2186 the system to accomplish the movement to the next page. 2187 3.188 Graphic Character 2188 A member of the graph character class of the current locale. 2189 Note: The graph character class is defined in detail in Section 7.3.1 (on page 147). 2190 3.189 Group Database 2191 A system database of implementation-defined format that contains at least the following | 2192 information for each group ID: 2193 * Group name 2194 * Numerical group ID 2195 * List of users allowed in the group 2196 The list of users allowed in the group is used by the newgrp utility. 2197 Note: The newgrp utility is defined in detail in the Shell and Utilities volume of | 2198 IEEE Std. 1003.1-200x. | 2199 3.190 Group ID 2200 A non-negative integer, which can be contained in an object of type gid_t, that is used to identify 2201 a group of system users. Each system user is a member of at least one group. When the identity 2202 of a group is associated with a process, a group ID value is referred to as a real group ID, an 2203 effective group ID, one of the supplementary group IDs, or a saved set-group-ID. 2204 3.191 Group Name 2205 A string that is used to identify a group; see also Section 3.189. To be portable across conforming | 2206 systems, the value is composed of characters from the portable file name character set. The | 2207 hyphen should not be used as the first character of a portable group name. | Base Definitions, Issue 6 73 Hard Limit Definitions 2208 3.192 Hard Limit 2209 A system resource limitation that may be reset to a lesser or greater limit by a privileged process. | 2210 A non-privileged process is restricted to only lowering its hard limit. | 2211 3.193 Hard Link 2212 The relationship between two directory entries that represent the same file; see also Section 3.132 2213 (on page 63). The result of an execution of the ln utility (without the -s option) or the link( ) | 2214 function. This term is contrasted against symbolic link; see also Section 3.374 (on page 104). | 2215 3.194 Home Directory 2216 The directory specified by the HOME environment variable. | 2217 3.195 Host Byte Order 2218 The arrangement of bytes in any int type when using a specific machine architecture. | 2219 Note: Two common methods of byte ordering are big-endian and little-endian. Big-endian | 2220 is a format for storage of binary data in which the most significant byte is placed first, | 2221 with the rest in descending order. Little-endian is a format for storage or | 2222 transmission of binary data in which the least significant byte is placed first, with the | 2223 rest in ascending order. | 2224 3.196 Incomplete Line 2225 A sequence of one or more non- characters at the end of the file. 2226 3.197 Inf 2227 A value representing infinity that can be stored in a floating type. Not all systems support the 2228 Inf value. | 74 Technical Standard (2000) (Draft July 28, 2000) Definitions Instrumented Application 2229 3.198 Instrumented Application | 2230 An application that contains at least one call to the trace point function posix_trace_event( ). Each | 2231 process of an instrumented application has a mapping of trace event names to trace event type | 2232 identifiers. This mapping is used by the trace stream that is created for that process. | 2233 3.199 Interactive Shell 2234 A processing mode of the shell that is suitable for direct user interaction. 2235 3.200 Internationalization 2236 The provision within a computer program of the capability of making itself adaptable to the 2237 requirements of different native languages, local customs, and coded character sets. 2238 3.201 Interprocess Communication 2239 A functionality enhancement to add a high-performance, deterministic interprocess 2240 communication facility for local communication. 2241 3.202 Invoke 2242 To perform command search and execution actions, except that searching for shell functions and 2243 special built-in utilities is suppressed; see also Section 3.156 (on page 67). 2244 Note: Command Search and Execution is defined in detail in the Shell and Utilities volume | 2245 of IEEE Std. 1003.1-200x, Section 2.9.1.1, Command Search and Execution. | 2246 3.203 Job 2247 A set of processes, comprising a shell pipeline, and any processes descended from it, that are all 2248 in the same process group. 2249 Note: See also the Shell and Utilities volume of IEEE Std. 1003.1-200x, Section 2.9.2, | 2250 Pipelines. | Base Definitions, Issue 6 75 Job Control Definitions 2251 3.204 Job Control 2252 A facility that allows users selectively to stop (suspend) the execution of processes and continue 2253 (resume) their execution at a later point. The user typically employs this facility via the 2254 interactive interface jointly supplied by the terminal I/O driver and a command interpreter. 2255 3.205 Job Control Job ID 2256 A handle that is used to refer to a job. The job control job ID can be any of the forms shown in the | 2257 following table: 2258 Table 3-1 Job Control Job ID Formats ___________________________________________________ | 2259 Job Control | 2260 Job ID Meaning | ___________________________________________________ | 2261 %% Current job. | 2262 %+ Current job. | 2263 %- Previous job. | 2264 %n Job number n. | 2265 %string Job whose command begins with string. | 2266 %?string Job whose command contains string. | ___________________________________________________ |||| 2267 3.206 Last Close (of a File) 2268 When a process closes a file, resulting in the file not being an open file within any process. 2269 3.207 Line 2270 A sequence of zero or more non- characters plus a terminating character. 2271 3.208 Linger 2272 Wait for a period of time before terminating a connection, to allow outstanding data to be 2273 transferred. 76 Technical Standard (2000) (Draft July 28, 2000) Definitions Link 2274 3.209 Link 2275 See Directory Entry in Section 3.132 (on page 63). | 2276 3.210 Link Count 2277 The number of directory entries that refer to a particular file. 2278 3.211 Local Customs 2279 The conventions of a geographical area or territory for such things as date, time, and currency 2280 formats. 2281 3.212 Local Interprocess Communication (Local IPC) 2282 The transfer of data between processes in the same system. 2283 3.213 Locale 2284 The definition of the subset of a user's environment that depends on language and cultural 2285 conventions. 2286 Note: Locales are defined in detail in Chapter 7 (on page 143). 2287 3.214 Localization 2288 The process of establishing information within a computer system specific to the operation of 2289 particular native languages, local customs, and coded character sets. 2290 3.215 Login 2291 The unspecified activity by which a user gains access to the system. Each login is associated 2292 with exactly one login name. Base Definitions, Issue 6 77 Login Name Definitions 2293 3.216 Login Name 2294 A user name that is associated with a login. 2295 3.217 Map 2296 To create an association between a page-aligned range of the address space of a process and | 2297 some memory object, such that a reference to an address in that range of the address space 2298 results in a reference to the associated memory object. The mapped memory object is not 2299 necessarily memory-resident. | 2300 3.218 Marked Message 2301 A STREAMs message on which a certain flag is set. Marking a message gives the application | 2302 protocol-specific information. An application can use ioctl( ) to determine whether a given 2303 message is marked. | 2304 Note: The ioctl( ) function is defined in detail in the System Interfaces volume of 2305 IEEE Std. 1003.1-200x. 2306 3.219 Matched 2307 A state applying to a sequence of zero or more characters when the characters in the sequence 2308 correspond to a sequence of characters defined by a BRE or ERE pattern. 2309 Note: Regular Expressions are defined in detail in Chapter 9 (on page 195). 2310 3.220 Memory Mapped Files and Shared Memory Objects 2311 A performance improvement facility to allow for programs to access files as part of the address 2312 space and for separate application programs to have portions of their address space commonly 2313 accessible. 2314 3.221 Memory Object 2315 One of: 2316 * A file 2317 * A shared memory object | 2318 * A typed memory object | 2319 When used in conjunction with mmap( ), a memory object appears in the address space of the | 2320 calling process. | 2321 Note: The mmap( ) function is defined in detail in the System Interfaces volume of 2322 IEEE Std. 1003.1-200x. 78 Technical Standard (2000) (Draft July 28, 2000) Definitions Memory-Resident 2323 3.222 Memory-Resident 2324 Managed by the implementation in such a way as to provide an upper bound on memory access 2325 times. 2326 3.223 Message 2327 In the context of programmatic message passing, information that can be transferred between | 2328 processes or threads by being added to and removed from a message queue. A message consists 2329 of a fixed-size message buffer. | 2330 3.224 Message Catalog 2331 In the context of providing natural language messages to the user, a file or storage area | 2332 containing program messages, command prompts, and responses to prompts for a particular 2333 native language, territory, and codeset. | 2334 3.225 Message Catalog Descriptor 2335 In the context of providing natural language messages to the user, a per-process unique value | 2336 used to identify an open message catalog. A message catalog descriptor may be implemented 2337 using a file descriptor. | 2338 3.226 Message Queue 2339 In the context of programmatic message passing, an object to which messages can be added and | 2340 removed. Messages may be removed in the order in which they were added or in priority order. | 2341 3.227 Mode 2342 A collection of attributes that specifies a file's type and its access permissions. 2343 Note: File Access Permissions are defined in detail in Section 4.3 (on page 121). Base Definitions, Issue 6 79 Monotonic Clock Definitions 2344 3.228 Monotonic Clock 2345 A clock whose value cannot be set via clock_settime( ) and which cannot have negative clock | 2346 jumps. | 2347 3.229 Mount Point 2348 Either the system root directory or a directory for which the st_dev field of structure stat differs 2349 from that of its parent directory. 2350 Note: The stat structure is defined in detail in . 2351 3.230 Multi-Character Collating Element 2352 A sequence of two or more characters that collate as an entity. For example, in some coded 2353 character sets, an accented character is represented by a non-spacing accent, followed by the 2354 letter. Other examples are the Spanish elements ch and ll. 2355 3.231 Mutex 2356 A synchronization object used to allow multiple threads to serialize their access to shared data. | 2357 The name derives from the capability it provides; namely, mutual-exclusion. The thread that has 2358 locked a mutex becomes its owner and remains the owner until that same thread unlocks the 2359 mutex. | 2360 3.232 Name 2361 In the shell command language, a word consisting solely of underscores, digits, and alphabetics 2362 from the portable character set. The first character of a name is not a digit. | 2363 Note: The Portable Character Set is defined in detail in Section 6.1 (on page 133). 2364 3.233 Named STREAM 2365 A STREAMS-based file descriptor that is attached to a name in the file system name space. All | 2366 subsequent operations on the named STREAM act on the STREAM that was associated with the 2367 file descriptor until the name is disassociated from the STREAM. | 80 Technical Standard (2000) (Draft July 28, 2000) Definitions NaN (Not a Number) 2368 3.234 NaN (Not a Number) 2369 A value that can be stored in a floating type but that is not a valid floating point number. Not all 2370 systems support the NaN value. 2371 3.235 Native Language 2372 A computer user's spoken or written language, such as American English, British English, 2373 Danish, Dutch, French, German, Italian, Japanese, Norwegian, or Swedish. 2374 3.236 Negative Response 2375 An input string that matches one of the responses acceptable to the LC_MESSAGES category 2376 keyword noexpr, matching an extended regular expression in the current locale. 2377 Note: The LC_MESSAGES category is defined in detail in Section 7.3.6 (on page 174). 2378 3.237 Network 2379 A collection of interconnected hosts. | 2380 Note: The term network in IEEE Std. 1003.1-200x is used to refer to the network of hosts. | 2381 The term batch system is used to refer to the network of batch servers. | 2382 3.238 Network Address 2383 A network-visible identifier used to designate specific endpoints in a network. Specific | 2384 endpoints on host systems have addresses, and host systems may also have addresses. | 2385 3.239 Network Byte Order 2386 The way of representing any int type such that, when transmitted over a network via a network | 2387 endpoint, the int type is transmitted as an appropriate number of octets with the most | 2388 significant octet first, followed by any other octets in descending order of significance. | 2389 Note: This order is more commonly known as big-endian ordering. | Base Definitions, Issue 6 81 Newline Character () Definitions 2390 3.240 Newline Character () 2391 A character that in the output stream indicates that printing should start at the beginning of the | 2392 next line. The character is the character designated by '\n' in the C language. It is | 2393 unspecified whether this character is the exact sequence transmitted to an output device by the 2394 system to accomplish the movement to the next line. 2395 3.241 Nice Value 2396 A number used as advice to the system to alter process scheduling. Numerically smaller values 2397 give a process additional preference when scheduling a process to run. Numerically larger 2398 values reduce the preference and make a process less likely to run. Typically, a process with a 2399 smaller nice value runs to completion more quickly than an equivalent process with a higher 2400 nice value. The symbol {NZERO} specifies the default nice value of the system. | 2401 3.242 Non-Blocking 2402 A property of an open file description that causes it to either perform the requested action or | 2403 return an indication that the action could not be immediately performed, in either case returning | 2404 without delay (other than normal scheduling delays) from the call. | 2405 Note: The exact semantics are dependent on the type of file associated with the open file. | 2406 For data reads from devices such as ttys and FIFOs, a successful return usually | 2407 indicates that data sufficient to satisfy the read was immediately available. Similarly, | 2408 for writes, that space to perform (at least part of) the write was available, and for | 2409 networking not to await protocol events (for example, acknowledgements) to occur. | 2410 3.243 Non-Spacing Characters 2411 A character, such as a character representing a diacritical mark in the ISO/IEC 6937: 1994 2412 standard coded character set, which is used in combination with other characters to form 2413 composite graphic symbols. 2414 3.244 NUL 2415 A character with all bits set to zero. 82 Technical Standard (2000) (Draft July 28, 2000) Definitions Null Byte 2416 3.245 Null Byte 2417 A byte with all bits set to zero. 2418 3.246 Null Pointer 2419 The value that is obtained by converting the number 0 into a pointer; for example, (void *) 0. The 2420 C language guarantees that this value does not match that of any legitimate pointer, so it is used 2421 by many functions that return pointers to indicate an error. 2422 3.247 Null String 2423 See Empty String in Section 3.147 (on page 66). 2424 3.248 Null Wide-Character Code 2425 A wide-character code with all bits set to zero. 2426 3.249 Number Sign 2427 The character '#', also known as hash sign. 2428 3.250 Object File 2429 A regular file containing the output of a compiler, formatted as input to a linkage editor for 2430 linking with other object files into an executable form. The methods of linking are unspecified 2431 and may involve the dynamic linking of objects at runtime. The internal format of an object file 2432 is unspecified, but a conforming application cannot assume an object file is a text file. 2433 3.251 Octet 2434 Unit of data representation that consists of eight contiguous bits. Base Definitions, Issue 6 83 Offset Maximum Definitions 2435 3.252 Offset Maximum 2436 An attribute of an open file description representing the largest value that can be used as a file | 2437 offset. | 2438 3.253 Opaque Address 2439 An address such that the entity making use of it requires no details about its contents or format. 2440 3.254 Open File 2441 A file that is currently associated with a file descriptor. 2442 3.255 Open File Description 2443 A record of how a process or group of processes is accessing a file. Each file descriptor refers to | 2444 exactly one open file description, but an open file description can be referred to by more than | 2445 one file descriptor. A file offset, file status, and file access modes are attributes of an open file 2446 description. 2447 3.256 Operand 2448 An argument to a command that is generally used as an object supplying information to a utility 2449 necessary to complete its processing. Operands generally follow the options in a command line. 2450 Note: Utility Argument Syntax is defined in detail in Section 12.1 (on page 227). 2451 3.257 Operator 2452 In the shell command language, either a control operator or a redirection operator. 2453 3.258 Option 2454 An argument to a command that is generally used to specify changes in the utility's default 2455 behavior. 2456 Note: Utility Argument Syntax is defined in detail in Section 12.1 (on page 227). 84 Technical Standard (2000) (Draft July 28, 2000) Definitions Option-Argument 2457 3.259 Option-Argument 2458 A parameter that follows certain options. In some cases an option-argument is included within 2459 the same argument string as the option-in most cases it is the next argument. 2460 Note: Utility Argument Syntax is defined in detail in Section 12.1 (on page 227). 2461 3.260 Orientation 2462 A stream has one of three orientations: unoriented, byte-oriented, or wide-oriented. 2463 Note: For further information, see the System Interfaces volume of IEEE Std. 1003.1-200x, 2464 Section 2.5.2, Stream Orientation and Encoding Rules. 2465 3.261 Orphaned Process Group 2466 A process group in which the parent of every member is either itself a member of the group or is 2467 not a member of the group's session. 2468 3.262 Page 2469 The granularity of process memory mapping or locking. 2470 Physical memory and memory objects can be mapped into the address space of a process on 2471 page boundaries and in integral multiples of pages. Process address space can be locked into 2472 memory (made memory-resident) on page boundaries and in integral multiples of pages. 2473 3.263 Page Size 2474 The size, in bytes, of the system unit of memory allocation, protection, and mapping. On systems | 2475 that have segment rather than page-based memory architectures, the term page means a | 2476 segment. | 2477 3.264 Parameter 2478 In the shell command language, an entity that stores values. There are three types of parameters: 2479 variables (named parameters), positional parameters, and special parameters. Parameter 2480 expansion is accomplished by introducing a parameter with the '$' character. 2481 Note: See also the Shell and Utilities volume of IEEE Std. 1003.1-200x, Section 2.5, | 2482 Parameters and Variables. | 2483 In the C language, an object declared as part of a function declaration or definition that acquires 2484 a value on entry to the function, or an identifier following the macro name in a function-like 2485 macro definition. Base Definitions, Issue 6 85 Parent Directory Definitions 2486 3.265 Parent Directory 2487 When discussing a given directory, the directory that both contains a directory entry for the 2488 given directory and is represented by the path name dot-dot in the given directory. 2489 When discussing other types of files, a directory containing a directory entry for the file under 2490 discussion. 2491 This concept does not apply to dot and dot-dot. 2492 3.266 Parent Process 2493 The process which created (or inherited) the process under discussion. 2494 3.267 Parent Process ID 2495 An attribute of a new process identifying the parent of the process. The parent process ID of a 2496 process is the process ID of its creator, for the lifetime of the creator. After the creator's lifetime 2497 has ended, the parent process ID is the process ID of an implementation-defined system process. | 2498 3.268 Path Name 2499 A character string that is used to identify a file. In the context of IEEE Std. 1003.1-200x, a path | 2500 name consists of, at most, {PATH_MAX} bytes, including the terminating null byte. It has an | 2501 optional beginning slash, followed by zero or more file names separated by slashes. A path name 2502 may optionally contain one or more trailing slashes. Multiple successive slashes are considered 2503 to be the same as one slash. | 2504 Note: Path Name Resolution is defined in detail in Section 4.9 (on page 123). 2505 3.269 Path Name Component 2506 See File Name in Section 3.171 (on page 70). 2507 3.270 Path Prefix 2508 A path name, with an optional ending slash, that refers to a directory. 86 Technical Standard (2000) (Draft July 28, 2000) Definitions Pattern 2509 3.271 Pattern 2510 A sequence of characters used either with regular expression notation or for path name 2511 expansion, as a means of selecting various character strings or path names, respectively. 2512 Note: Regular Expressions are defined in detail in Chapter 9 (on page 195). 2513 See also the Shell and Utilities volume of IEEE Std. 1003.1-200x, Section 2.6.6, Path | 2514 Name Expansion. | 2515 The syntaxes of the two types of patterns are similar, but not identical; IEEE Std. 1003.1-200x 2516 always indicates the type of pattern being referred to in the immediate context of the use of the 2517 term. 2518 3.272 Period 2519 The character '.'. The term period is contrasted with dot (see also Section 3.137 (on page 64)), | 2520 which is used to describe a specific directory entry. 2521 3.273 Permissions 2522 Attributes of an object that determine the privilege necessary to access or manipulate the object. | 2523 Note: File Access Permissions are defined in detail in Section 4.3 (on page 121). 2524 3.274 Persistence 2525 A mode for semaphores, shared memory, and message queues requiring that the object and its 2526 state (including data, if any) are preserved after the object is no longer referenced by any process. 2527 Persistence of an object does not imply that the state of the object is maintained across a system 2528 crash or a system reboot. 2529 3.275 Pipe 2530 An object accessed by one of the pair of file descriptors created by the pipe( ) function. Once 2531 created, the file descriptors can be used to manipulate it, and it behaves identically to a FIFO 2532 special file when accessed in this way. It has no name in the file hierarchy. 2533 Note: The pipe( ) function is defined in detail in the System Interfaces volume of 2534 IEEE Std. 1003.1-200x. Base Definitions, Issue 6 87 Polling Definitions 2535 3.276 Polling 2536 A scheduling scheme whereby the local process periodically checks until the prespecified events 2537 (for example, read, write) have occurred. 2538 3.277 Portable Character Set 2539 The collection of characters that are required to be present in all locales supported by 2540 conforming systems. 2541 Note: The Portable Character Set is defined in detail in Section 6.1 (on page 133). 2542 This term is contrasted against the smaller portable file name character set; see also Section 3.278. 2543 3.278 Portable File Name Character Set 2544 The set of characters from which portable file names are constructed. 2545 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z | 2546 a b c d e f g h i j k l m n o p q r s t u v w x y z | 2547 0 1 2 3 4 5 6 7 8 9 . _ - | 2548 The last three characters are the period, underscore, and hyphen characters, respectively. 2549 3.279 Positional Parameter 2550 In the shell command language, a parameter denoted by a single digit or one or more digits in 2551 curly braces. 2552 Note: For further information, see the Shell and Utilities volume of IEEE Std. 1003.1-200x, | 2553 Section 2.5.1, Positional Parameters. | 2554 3.280 Preallocation 2555 The reservation of resources in a system for a particular use. 2556 Preallocation does not imply that the resources are immediately allocated to that use, but merely 2557 indicates that they are guaranteed to be available in bounded time when needed. 88 Technical Standard (2000) (Draft July 28, 2000) Definitions Preempted Process (or Thread) 2558 3.281 Preempted Process (or Thread) 2559 A running thread whose execution is suspended due to another thread becoming runnable at a 2560 higher priority. | 2561 3.282 Previous Job | 2562 In the context of job control, the job that will be used as the default for the fg or bg utilities if the | 2563 current job exits. There is at most one previous job; see also Section 3.205 (on page 76). | 2564 3.283 Printable Character 2565 One of the characters included in the print character classification of the LC_CTYPE category in 2566 the current locale. 2567 Note: The LC_CTYPE category is defined in detail in Section 7.3.1 (on page 147). 2568 3.284 Printable File 2569 A text file consisting only of the characters included in the print and space character 2570 classifications of the LC_CTYPE category and the character, all in the current locale. 2571 Note: The LC_CTYPE category is defined in detail in Section 7.3.1 (on page 147). 2572 3.285 Priority 2573 A non-negative integer associated with processes or threads whose value is constrained to a | 2574 range defined by the applicable scheduling policy. Numerically higher values represent higher 2575 priorities. | 2576 3.286 Priority Band 2577 The queuing order applied to normal priority STREAMS messages. High priority STREAMS | 2578 messages are not grouped by priority bands. The only differentiation made by the STREAMS 2579 mechanism is between zero and non-zero bands, but specific protocol modules may differentiate 2580 between priority bands. | Base Definitions, Issue 6 89 Priority Inversion Definitions 2581 3.287 Priority Inversion 2582 A condition in which a thread that is not voluntarily suspended (waiting for an event or time 2583 delay) is not running while a lower priority thread is running. Such blocking of the higher 2584 priority thread is often caused by contention for a shared resource. 2585 3.288 Priority Scheduling 2586 A performance and determinism improvement facility to allow applications to determine the 2587 order in which threads that are ready to run are granted access to processor resources. 2588 3.289 Priority-Based Scheduling 2589 Scheduling in which the selection of a running thread is determined by the priorities of the | 2590 runnable processes or threads. | 2591 3.290 Privilege 2592 See Appropriate Privileges in Section 3.19 (on page 44). 2593 3.291 Process 2594 An address space with one or more threads executing within that address space, and the 2595 required system resources for those threads. 2596 Note: Many of the system resources defined by IEEE Std. 1003.1-200x are shared among all 2597 of the threads within a process. These include the process ID, the parent process ID, 2598 process group ID, session membership, real, effective, and saved-set user ID, real, 2599 effective, and saved-set group ID, supplementary group IDs, current working 2600 directory, root directory, file mode creation mask, and file descriptors. 2601 3.292 Process Group 2602 A collection of processes that permits the signaling of related processes. Each process in the 2603 system is a member of a process group that is identified by a process group ID. A newly created 2604 process joins the process group of its creator. 90 Technical Standard (2000) (Draft July 28, 2000) Definitions Process Group ID 2605 3.293 Process Group ID 2606 The unique positive integer identifier representing a process group during its lifetime. 2607 Note: See also Process Group ID Reuse defined in Section 4.10 (on page 124). 2608 3.294 Process Group Leader 2609 A process whose process ID is the same as its process group ID. 2610 3.295 Process Group Lifetime 2611 A period of time that begins when a process group is created and ends when the last remaining 2612 process in the group leaves the group, due either to the end of the last process' lifetime or to the 2613 last remaining process calling the setsid( ) or setpgid( ) functions. 2614 Note: The setsid( ) and setpgid( ) functions are defined in detail in the System Interfaces 2615 volume of IEEE Std. 1003.1-200x. 2616 3.296 Process ID 2617 The unique positive integer identifier representing a process during its lifetime. 2618 Note: See also Process ID Reuse defined in Section 4.10 (on page 124). 2619 3.297 Process Lifetime 2620 The period of time that begins when a process is created and ends when its process ID is 2621 returned to the system. After a process is created with a fork( ) function, it is considered active. 2622 At least one thread of control and address space exist until it terminates. It then enters an 2623 inactive state where certain resources may be returned to the system, although some resources, 2624 such as the process ID, are still in use. When another process executes a wait( ), waitid( ), or | 2625 waitpid( ) function for an inactive process, the remaining resources are returned to the system. 2626 The last resource to be returned to the system is the process ID. At this time, the lifetime of the 2627 process ends. 2628 Note: The fork( ), wait( ), waitid( ), and waitpid( ) functions are defined in detail in the System 2629 Interfaces volume of IEEE Std. 1003.1-200x. Base Definitions, Issue 6 91 Process Memory Locking Definitions 2630 3.298 Process Memory Locking 2631 A performance improvement facility to bind application programs into the high-performance 2632 random access memory of a computer system. This avoids potential latencies introduced by the 2633 operating system in storing parts of a program that were not recently referenced on secondary 2634 memory devices. 2635 3.299 Process Termination 2636 There are two kinds of process termination: 2637 1. Normal termination occurs by a return from main( ) or when requested with the exit( ) or 2638 _exit( ) functions. 2639 2. Abnormal termination occurs when requested by the abort( ) function or when some 2640 signals are received. 2641 Note: The _exit( ), abort( ), and exit( ) functions are defined in detail in the System Interfaces 2642 volume of IEEE Std. 1003.1-200x. 2643 3.300 Process-To-Process Communication 2644 The transfer of data between processes. 2645 3.301 Process Virtual Time 2646 The measurement of time in units elapsed by the system clock while a process is executing. | 2647 3.302 Program 2648 A prepared sequence of instructions to the system to accomplish a defined task. The term | 2649 program in IEEE Std. 1003.1-200x encompasses applications written in the Shell Command | 2650 Language, complex utility input languages (for example, awk, lex, sed, and so on), and high-level | 2651 languages. 2652 3.303 Protocol 2653 A set of semantic and syntactic rules for exchanging information. 92 Technical Standard (2000) (Draft July 28, 2000) Definitions Pseudo-Terminal 2654 3.304 Pseudo-Terminal 2655 A pseudo-terminal provides the process with an interface that is identical to the terminal | 2656 subsystem. A pseudo-terminal is composed of two devices: the master device and a slave device. 2657 The slave device provides processes with an interface that is identical to the terminal interface, 2658 although there need not be hardware behind that interface. Anything written on the master 2659 device is presented to the slave as an input and anything written on the slave device is presented 2660 as an input on the master side. | 2661 3.305 Radix Character 2662 The character that separates the integer part of a number from the fractional part. 2663 3.306 Read-Only File System 2664 A file system that has implementation-defined characteristics restricting modifications. | 2665 Note: File Times Update is described in detail in Section 4.6 (on page 122). 2666 3.307 Read-Write Lock 2667 Multiple readers, single writer (read-write) locks allow many threads to have simultaneous | 2668 read-only access to data while allowing only one thread to have write access at any given time. 2669 They are typically used to protect data that is read-only more frequently than it is changed. 2670 Read-write locks can be used to synchronize threads in the current process and other processes if 2671 they are allocated in memory that is writable and shared among the cooperating processes and 2672 have been initialized for this behavior. | 2673 3.308 Real Group ID 2674 The attribute of a process that, at the time of process creation, identifies the group of the user 2675 who created the process; see also Section 3.190 (on page 73). 2676 3.309 Real Time 2677 Time measured as total units elapsed by the system clock without regard to which thread is | 2678 executing. | Base Definitions, Issue 6 93 Realtime Signal Extension Definitions 2679 3.310 Realtime Signal Extension 2680 A determinism improvement facility to enable asynchronous signal notifications to an | 2681 application to be queued without impacting compatibility with the existing signal functions. | 2682 3.311 Real User ID 2683 The attribute of a process that, at the time of process creation, identifies the user who created the 2684 process; see also Section 3.427 (on page 115). 2685 3.312 Record 2686 A collection of related data units or words which is treated as a unit. | 2687 3.313 Redirection 2688 In the shell command language, a method of associating files with the input or output of 2689 commands. 2690 Note: For further information, see the Shell and Utilities volume of IEEE Std. 1003.1-200x, | 2691 Section 2.7, Redirection. | 2692 3.314 Redirection Operator 2693 In the shell command language, a token that performs a redirection function. It is one of the 2694 following symbols: 2695 < > >| << >> <& >& <<- <> | 2696 3.315 Reentrant Function 2697 A function whose effect, when called by two or more threads, is guaranteed to be as if the 2698 threads each executed the function one after another in an undefined order, even if the actual 2699 execution is interleaved. 94 Technical Standard (2000) (Draft July 28, 2000) Definitions Referenced Shared Memory Object 2700 3.316 Referenced Shared Memory Object 2701 A shared memory object that is open or has one or more mappings defined on it. 2702 3.317 Refresh 2703 To ensure that the information on the user's terminal screen is up-to-date. 2704 3.318 Regular Expression 2705 A pattern that selects specific strings from a set of character strings. 2706 Note: Regular Expressions are described in detail in Chapter 9 (on page 195). 2707 3.319 Region 2708 In the context of the address space of a process, a sequence of addresses. 2709 In the context of a file, a sequence of offsets. 2710 3.320 Regular File 2711 A file that is a randomly accessible sequence of bytes, with no further structure imposed by the 2712 system. 2713 3.321 Relative Path Name 2714 A path name not beginning with a slash. | 2715 Note: Path Name Resolution is defined in detail in Section 4.9 (on page 123). 2716 3.322 Relocatable File 2717 A file holding code or data suitable for linking with other object files to create an executable or a 2718 shared object file. Base Definitions, Issue 6 95 Relocation Definitions 2719 3.323 Relocation 2720 The process of connecting symbolic references with symbolic definitions. For example, when a 2721 program calls a function, the associated call instruction transfers control to the proper 2722 destination address at execution. 2723 3.324 Requested Batch Service 2724 A service that is either rejected or performed prior to a response from the service to the | 2725 requester. | 2726 3.325 (Time) Resolution 2727 The minimum time interval that a clock can measure or whose passage a timer can detect. 2728 3.326 Root Directory 2729 A directory, associated with a process, that is used in path name resolution for path names that 2730 begin with a slash. 2731 3.327 Runnable Process (or Thread) 2732 A thread that is capable of being a running thread, but for which no processor is available. 2733 3.328 Running Process (or Thread) 2734 A thread currently executing on a processor. On multi-processor systems there may be more 2735 than one such thread in a system at a time. 2736 3.329 Saved Resource Limits 2737 An attribute of a process that provides some flexibility in the handling of unrepresentable | 2738 resource limits, as described in the exec family of functions and setrlimit( ). | 2739 Note: The exec and setrlimit( ) functions are defined in detail in the System Interfaces 2740 volume of IEEE Std. 1003.1-200x. 96 Technical Standard (2000) (Draft July 28, 2000) Definitions Saved Set-Group-ID 2741 3.330 Saved Set-Group-ID 2742 An attribute of a process that allows some flexibility in the assignment of the effective group ID 2743 attribute, as described in the exec family of functions and setgid( ). 2744 Note: The exec and setgid( ) functions are defined in detail in the System Interfaces volume 2745 of IEEE Std. 1003.1-200x. 2746 3.331 Saved Set-User-ID 2747 An attribute of a process that allows some flexibility in the assignment of the effective user ID 2748 attribute, as described in the exec family of functions and setuid( ). 2749 Note: The exec and setuid( ) functions are defined in detail in the System Interfaces volume 2750 of IEEE Std. 1003.1-200x. 2751 3.332 Scheduling 2752 The application of a policy to select a runnable process or thread to become a running process or 2753 thread, or to alter one or more of the thread lists. 2754 3.333 Scheduling Allocation Domain 2755 The set of processors on which an individual thread can be scheduled at any given time. 2756 3.334 Scheduling Contention Scope 2757 A property of a thread that defines the set of threads against which that thread competes for | 2758 resources. 2759 For example, in a scheduling decision, threads sharing scheduling contention scope compete for 2760 processor resources. In IEEE Std. 1003.1-200x, a thread has scheduling contention scope of either 2761 PTHREAD_SCOPE_SYSTEM or PTHREAD_SCOPE_PROCESS. | 2762 3.335 Scheduling Policy 2763 A set of rules that is used to determine the order of execution of processes or threads to achieve | 2764 some goal. | 2765 Note: Scheduling Policy is defined in detail in Section 4.11 (on page 125). | Base Definitions, Issue 6 97 Screen Definitions 2766 3.336 Screen 2767 A rectangular region of columns and lines on a terminal display. A screen may be a portion of a 2768 physical display device or may occupy the entire physical area of the display device. 2769 3.337 Scroll 2770 To move the representation of data vertically or horizontally relative to the terminal screen. 2771 There are two types of scrolling: 2772 1. The cursor moves with the data. 2773 2. The cursor remains stationary while the data moves. 2774 3.338 Semaphore 2775 A minimum synchronization primitive to serve as a basis for more complex synchronization | 2776 mechanisms to be defined by the application program. | 2777 Note: Semaphores are defined in detail in Section 4.13 (on page 126). | 2778 3.339 Session 2779 A collection of process groups established for job control purposes. Each process group is a 2780 member of a session. A process is considered to be a member of the session of which its process 2781 group is a member. A newly created process joins the session of its creator. A process can alter 2782 its session membership; see setsid( ). There can be multiple process groups in the same session. 2783 Note: The setsid( ) function is defined in detail in the System Interfaces volume of 2784 IEEE Std. 1003.1-200x. 2785 3.340 Session Leader 2786 A process that has created a session. 2787 Note: For further information, see the setsid( ) function defined in the System Interfaces 2788 volume of IEEE Std. 1003.1-200x. 98 Technical Standard (2000) (Draft July 28, 2000) Definitions Session Lifetime 2789 3.341 Session Lifetime 2790 The period between when a session is created and the end of the lifetime of all the process 2791 groups that remain as members of the session. 2792 3.342 Shared Memory Object 2793 An object that represents memory that can be mapped concurrently into the address space of | 2794 more than one process. | 2795 3.343 Shell 2796 A program that interprets sequences of text input as commands. It may operate on an input 2797 stream or it may interactively prompt and read commands from a terminal. 2798 3.344 Shell, the 2799 The Shell Command Language Interpreter; a specific instance of a shell. 2800 Note: For further information, see the sh utility defined in the Shell and Utilities volume of | 2801 IEEE Std. 1003.1-200x. | 2802 3.345 Shell Script 2803 A file containing shell commands. If the file is made executable, it can be executed by specifying 2804 its name as a simple command. Execution of a shell script causes a shell to execute the 2805 commands within the script. Alternatively, a shell can be requested to execute the commands in 2806 a shell script by specifying the name of the shell script as the operand to the sh utility. 2807 Note: Simple Commands are defined in detail in the Shell and Utilities volume of | 2808 IEEE Std. 1003.1-200x, Section 2.9.1, Simple Commands. | 2809 The sh utility is defined in detail in the Shell and Utilities volume of | 2810 IEEE Std. 1003.1-200x. | 2811 3.346 Signal 2812 A mechanism by which a process or thread may be notified of, or affected by, an event occurring 2813 in the system. Examples of such events include hardware exceptions and specific actions by 2814 processes. The term signal is also used to refer to the event itself. | Base Definitions, Issue 6 99 Signal Stack Definitions 2815 3.347 Signal Stack 2816 Memory established for a thread, in which signal handlers catching signals sent to that thread | 2817 are executed. | 2818 3.348 Single-Quote 2819 The character ''', also known as apostrophe. 2820 3.349 Slash 2821 The character '/', also known as solidus. 2822 3.350 Socket 2823 A file of a particular type that is used as a communications endpoint for process-to-process 2824 communication as described in the System Interfaces volume of IEEE Std. 1003.1-200x. 2825 3.351 Socket Address 2826 An address associated with a socket or remote endpoint, including an address family identifier 2827 and addressing information specific to that address family. The address may include multiple 2828 parts, such as a network address associated with a host system and an identifier for a specific 2829 endpoint. 2830 3.352 Soft Limit 2831 A resource limitation established for each process that the process may set to any value less than | 2832 or equal to the hard limit. | 2833 3.353 Source Code 2834 When dealing with the Shell Command Language, input to the command language interpreter. | 2835 The term shell script is synonymous with this meaning. | 2836 When dealing with an ISO/IEC-conforming programming language, source code is input to a 2837 compiler conforming to that ISO/IEC standard. 2838 Source code also refers to the input statements prepared for the following standard utilities: 2839 awk, bc, ed, lex, localedef, make, sed, and yacc. 2840 Source code can also refer to a collection of sources meeting any or all of these meanings. 2841 Note: The awk, bc, ed, lex, localedef, make, sed, and yacc utilities are defined in detail in the | 2842 Shell and Utilities volume of IEEE Std. 1003.1-200x. | 100 Technical Standard (2000) (Draft July 28, 2000) Definitions Space Character () 2843 3.354 Space Character () 2844 The character defined in the portable character set as . The character is a 2845 member of the space character class of the current locale, but represents the single character, and 2846 not all of the possible members of the class; see also Section 3.433 (on page 116). 2847 3.355 Spawn 2848 A process creation primitive useful for systems that have difficulty with fork( ) and as an efficient | 2849 replacement for fork( )/exec. | 2850 3.356 Special Built-In 2851 See Built-In Utility in Section 3.85 (on page 55). 2852 3.357 Special Parameter 2853 In the shell command language, a parameter named by a single character from the following list: 2854 * @ # ? ! - $ 0 | 2855 Note: For further information, see the Shell and Utilities volume of IEEE Std. 1003.1-200x, | 2856 Section 2.5.2, Special Parameters. | 2857 3.358 Spin Lock 2858 A synchronization object used to allow multiple threads to serialize their access to shared data. | 2859 3.359 Sporadic Server 2860 A scheduling policy for threads and processes that reserves a certain amount of execution | 2861 capacity for processing aperiodic events at a given priority level. | 2862 3.360 Standard Error 2863 An output stream usually intended to be used for diagnostic messages. Base Definitions, Issue 6 101 Standard Input Definitions 2864 3.361 Standard Input 2865 An input stream usually intended to be used for primary data input. 2866 3.362 Standard Output 2867 An output stream usually intended to be used for primary data output. 2868 3.363 Standard Utilities 2869 The utilities described in the Shell and Utilities volume of IEEE Std. 1003.1-200x. | 2870 3.364 Stream 2871 Appearing in lowercase, a stream is a file access object that allows access to an ordered sequence 2872 of characters, as described by the ISO C standard. Such objects can be created by the fdopen( ), 2873 fopen( ), or popen( ) functions, and are associated with a file descriptor. A stream provides the 2874 additional services of user-selectable buffering and formatted input and output; see also Section 2875 3.365. 2876 Note: For further information, see the System Interfaces volume of IEEE Std. 1003.1-200x, 2877 Section 2.5, Standard I/O Streams. 2878 The fdopen( ), fopen( ), or popen( ) functions are defined in detail in the System 2879 Interfaces volume of IEEE Std. 1003.1-200x. 2880 3.365 STREAM 2881 Appearing in uppercase, STREAM refers to a full duplex connection between a process and an | 2882 open device or pseudo-device. It optionally includes one or more intermediate processing 2883 modules that are interposed between the process end of the STREAM and the device driver (or 2884 pseudo-device driver) end of the STREAM; see also Section 3.364. | 2885 Note: For further information, see the System Interfaces volume of IEEE Std. 1003.1-200x, 2886 Section 2.6, STREAMS. 102 Technical Standard (2000) (Draft July 28, 2000) Definitions STREAM End 2887 3.366 STREAM End 2888 The STREAM end is the driver end of the STREAM and is also known as the downstream end of | 2889 the STREAM. | 2890 3.367 STREAM Head 2891 The STREAM head is the beginning of the STREAM and is at the boundary between the system | 2892 and the application process. This is also known as the upstream end of the STREAM. | 2893 3.368 STREAMS Multiplexor 2894 A driver with multiple STREAMS connected to it. Multiplexing with STREAMS connected above | 2895 is referred to as N-to-1, or upper multiplexing. Multiplexing with STREAMS connected below is 2896 referred to as 1-to-N or lower multiplexing. | 2897 3.369 String 2898 A contiguous sequence of bytes terminated by and including the first null byte. 2899 3.370 Subshell 2900 A shell execution environment, distinguished from the main or current shell execution 2901 environment. 2902 Note: For further information, see the Shell and Utilities volume of IEEE Std. 1003.1-200x, | 2903 Section 2.13, Shell Execution Environment. | 2904 3.371 Successfully Transferred 2905 For a write operation to a regular file, when the system ensures that all data written is readable 2906 on any subsequent open of the file (even one that follows a system or power failure) in the 2907 absence of a failure of the physical storage medium. 2908 For a read operation, when an image of the data on the physical storage medium is available to 2909 the requesting process. Base Definitions, Issue 6 103 Supplementary Group ID Definitions 2910 3.372 Supplementary Group ID 2911 An attribute of a process used in determining file access permissions. A process has up to 2912 {NGROUPS_MAX} supplementary group IDs in addition to the effective group ID. The 2913 supplementary group IDs of a process are set to the supplementary group IDs of the parent 2914 process when the process is created. | 2915 3.373 Suspended Job 2916 A job that has received a SIGSTOP, SIGTSTP, SIGTTIN, or SIGTTOU signal that caused the 2917 process group to stop. A suspended job is a background job, but a background job is not 2918 necessarily a suspended job. 2919 3.374 Symbolic Link 2920 A type of file with the property that when the file is encountered during path name resolution, a 2921 string stored by the file is used to modify the path name resolution. The stored string has a 2922 length of {SYMLINK_MAX} bytes or fewer. 2923 Note: Path Name Resolution is defined in detail in Section 4.9 (on page 123). 2924 3.375 Synchronized Input and Output 2925 A determinism and robustness improvement mechanism to enhance the data input and output 2926 mechanisms, so that an application can ensure that the data being manipulated is physically 2927 present on secondary mass storage devices. 2928 3.376 Synchronized I/O Completion 2929 The state of an I/O operation that has either been successfully transferred or diagnosed as | 2930 unsuccessful. | 2931 3.377 Synchronized I/O Data Integrity Completion 2932 For read, when the operation has been completed or diagnosed if unsuccessful. The read is | 2933 complete only when an image of the data has been successfully transferred to the requesting 2934 process. If there were any pending write requests affecting the data to be read at the time that 2935 the synchronized read operation was requested, these write requests are successfully transferred | 2936 prior to reading the data. | 2937 For write, when the operation has been completed or diagnosed if unsuccessful. The write is 2938 complete only when the data specified in the write request is successfully transferred and all file 2939 system information required to retrieve the data is successfully transferred. 2940 File attributes that are not necessary for data retrieval (access time, modification time, status 2941 change time) need not be successfully transferred prior to returning to the calling process. | 104 Technical Standard (2000) (Draft July 28, 2000) Definitions Synchronized I/O File Integrity Completion 2942 3.378 Synchronized I/O File Integrity Completion 2943 Identical to a synchronized I/O data integrity completion with the addition that all file attributes | 2944 relative to the I/O operation (including access time, modification time, status change time) are 2945 successfully transferred prior to returning to the calling process. | 2946 3.379 Synchronized I/O Operation 2947 An I/O operation performed on a file that provides the application assurance of the integrity of | 2948 its data and files. | 2949 3.380 Synchronous I/O Operation 2950 An I/O operation that causes the thread requesting the I/O to be blocked from further use of the 2951 processor until that I/O operation completes. 2952 Note: A synchronous I/O operation does not imply synchronized I/O data integrity 2953 completion or synchronized I/O file integrity completion. 2954 3.381 Synchronously-Generated Signal 2955 A signal that is attributable to a specific thread. 2956 For example, a thread executing an illegal instruction or touching invalid memory causes a 2957 synchronously-generated signal. Being synchronous is a property of how the signal was 2958 generated and not a property of the signal number. 2959 3.382 System 2960 An implementation of IEEE Std. 1003.1-200x. 2961 3.383 System Crash 2962 An interval initiated by an unspecified circumstance that causes all processes (possibly other 2963 than special system processes) to be terminated in an undefined manner, after which any 2964 changes to the state and contents of files created or written to by an application prior to the 2965 interval are undefined, except as required elsewhere in IEEE Std. 1003.1-200x. Base Definitions, Issue 6 105 System Console Definitions 2966 3.384 System Console 2967 An optional file that receives messages sent by fmtmsg( ) when the MM_CONSOLE flag is set. | 2968 Note: The fmtmsg( ) function is defined in detail in the System Interfaces volume of 2969 IEEE Std. 1003.1-200x. 2970 3.385 System Databases 2971 An implementation provides two system databases. 2972 The group database contains the following information for each group: 2973 1. Group name 2974 2. Numerical group ID 2975 3. List of all users allowed in the group 2976 The user database contains the following information for each user: 2977 1. User name 2978 2. Numerical user ID 2979 3. Numerical group ID 2980 4. Initial working directory 2981 5. Initial user program 2982 If the initial user program field is null, the system default is used. If the initial working directory 2983 field is null, the interpretation of that field is implementation-defined. These databases may | 2984 contain other fields that are unspecified by IEEE Std. 1003.1-200x. | 2985 3.386 System Documentation 2986 All documentation provided with an implementation except for the conformance document or | 2987 Conformance Statement Questionnaire (CSQ). Electronically distributed documents for an | 2988 implementation are considered part of the system documentation. 2989 3.387 System Process 2990 An implementation-defined object, other than a process executing an application, that has a | 2991 process ID. 106 Technical Standard (2000) (Draft July 28, 2000) Definitions System Reboot 2992 3.388 System Reboot 2993 An implementation-defined sequence of events that may result in the loss of transitory data; that | 2994 is, data that is not saved in permanent storage. For example, message queues, shared memory, 2995 semaphores, and processes. | 2996 3.389 System Trace Event | 2997 A trace event that is generated by the implementation, in response either to a system-initiated | 2998 action or to an application-requested action, except for a call to posix_trace_event( ). When | 2999 supported by the implementation, a system-initiated action generates a process-independent | 3000 system trace event and an application-requested action generates a process-dependent system | 3001 trace event. For a system trace event not defined by IEEE Std. 1003.1-200x, the associated trace | 3002 event type identifier is derived from the implementation-defined name for this trace event, and | 3003 the associated data is of implementation-defined content and length. | 3004 3.390 System-Wide 3005 Pertaining to events occurring in all processes existing in an implementation at a given point in 3006 time. 3007 3.391 Tab Character () 3008 A character that in the output stream indicates that printing or displaying should start at the 3009 next horizontal tabulation position on the current line. The character is the character | 3010 designated by '\t' in the C language. If the current position is at or past the last defined | 3011 horizontal tabulation position, the behavior is unspecified. It is unspecified whether this 3012 character is the exact sequence transmitted to an output device by the system to accomplish the 3013 tabulation. 3014 3.392 Terminal (or Terminal Device) 3015 A character special file that obeys the specifications of the general terminal interface. 3016 Note: The General Terminal Interface is defined in detail in Chapter 11 (on page 213). Base Definitions, Issue 6 107 Text Column Definitions 3017 3.393 Text Column 3018 A roughly rectangular block of characters capable of being laid out side-by-side next to other 3019 text columns on an output page or terminal screen. The widths of text columns are measured in 3020 column positions. 3021 3.394 Text File 3022 A file that contains characters organized into one or more lines. The lines do not contain NUL | 3023 characters and none can exceed {LINE_MAX} bytes in length, including the character. | 3024 Although IEEE Std. 1003.1-200x does not distinguish between text files and binary files (see the 3025 ISO C standard), many utilities only produce predictable or meaningful output when operating 3026 on text files. The standard utilities that have such restrictions always specify text files in their 3027 STDIN or INPUT FILES sections. | 3028 3.395 Thread 3029 A single flow of control within a process. Each thread has its own thread ID, scheduling priority | 3030 and policy, errno value, thread-specific key/value bindings, and the required system resources to 3031 support a flow of control. Anything whose address may be determined by a thread, including 3032 but not limited to static variables, storage obtained via malloc( ), directly addressable storage | 3033 obtained through implementation-defined functions, and automatic variables, are accessible to | 3034 all threads in the same process. | 3035 Note: The malloc( ) function is defined in detail in the System Interfaces volume of 3036 IEEE Std. 1003.1-200x. 3037 3.396 Thread ID 3038 Each thread in a process is uniquely identified during its lifetime by a value of type pthread_t | 3039 called a thread ID. | 3040 3.397 Thread List 3041 An ordered set of runnable threads that all have the same ordinal value for their priority. | 3042 The ordering of threads on the list is determined by a scheduling policy or policies. The set of 3043 thread lists includes all runnable threads in the system. | 108 Technical Standard (2000) (Draft July 28, 2000) Definitions Thread-Safe 3044 3.398 Thread-Safe 3045 A function that may be safely invoked concurrently by multiple threads. Each function defined | 3046 in the System Interfaces volume of IEEE Std. 1003.1-200x is thread-safe unless explicitly stated 3047 otherwise. Examples are any ``pure'' function, a function which holds a mutex locked while it is 3048 accessing static storage, or objects shared among threads. | 3049 3.399 Thread-Specific Data Key 3050 A process global handle of type pthread_key_t which is used for naming thread-specific data. | 3051 Although the same key value may be used by different threads, the values bound to the key by 3052 pthread_setspecific( ) and accessed by pthread_getspecific( ) are maintained on a per-thread basis 3053 and persist for the life of the calling thread. | 3054 Note: The pthread_getspecific( ) and pthread_setspecific( ) functions are defined in detail in the 3055 System Interfaces volume of IEEE Std. 1003.1-200x. 3056 3.400 Tilde 3057 The character ' '. 3058 3.401 Timeouts 3059 A method of limiting the length of time an interface will block; see also Section 3.77 (on page 54). | 3060 3.402 Timer 3061 A mechanism that can notify a thread when the time as measured by a particular clock has | 3062 reached or passed a specified value, or when a specified amount of time has passed. | 3063 3.403 Timer Overrun 3064 A condition that occurs each time a timer, for which there is already an expiration signal queued | 3065 to the process, expires. | Base Definitions, Issue 6 109 Token Definitions 3066 3.404 Token 3067 In the shell command language, a sequence of characters that the shell considers as a single unit 3068 when reading input. A token is either an operator or a word. 3069 Note: The rules for reading input are defined in detail in the Shell and Utilities volume of | 3070 IEEE Std. 1003.1-200x, Section 2.3, Token Recognition. | 3071 3.405 Trace Analyzer Process | 3072 A process that extracts trace events from a trace stream to retrieve information about the | 3073 behavior of an application. A trace controller process may also be a trace analyzer process. Trace | 3074 analysis can be done concurrently with the traced process or can be done off-line, in the same or | 3075 in a different platform. | 3076 3.406 Trace Controller Process | 3077 A process that creates a trace stream for tracing a process. Only the trace controller process has | 3078 control of the trace stream it has created. The control of the operation of a trace stream is done | 3079 using its corresponding trace stream identifier. The trace controller process is able to: | 3080 * Initialize the attributes of a trace stream | 3081 * Create the trace stream | 3082 * Start and stop tracing | 3083 * Know the mapping of the traced process | 3084 * If the Trace Event Filter option is supported, filter the type of trace events to be recorded | 3085 * Shut the trace stream down | 3086 A traced process may also be a trace controller process. Only the trace controller process can | 3087 control its trace stream(s). A trace stream created by a trace controller process is shut down if its | 3088 controller process terminates or executes another file. | 3089 3.407 Trace Event | 3090 A data object that represents an action executed by the system, and that is recorded in a trace | 3091 stream. Each trace event is of a particular trace event type, and is associated with a trace event | 3092 type identifier. The execution of a trace point generates a trace event if a trace stream has been | 3093 created and started for the process that executed the trace point and if the corresponding trace | 3094 event type identifier is not ignored by filtering. | 3095 A generated trace event should be recorded in a trace stream and optionally also in a trace log if | 3096 a trace log was associated with the trace stream. | 3097 The only case in which a generated trace event is not recorded in the trace stream is when no | 3098 resources are available for it in the trace stream. In this case, the trace event is lost. | 3099 The only two cases in which a generated trace event is not recorded in the trace log are when no | 3100 resources are available for it in the trace log or when a flush operation does not succeed. | 3101 A trace event recorded in an active trace stream may be retrieved by an application having the | 3102 appropriate privileges. | 110 Technical Standard (2000) (Draft July 28, 2000) Definitions Trace Event 3103 A trace event recorded in a trace log may be retrieved by an application having the appropriate | 3104 privileges after opening the trace log as a pre-recorded trace stream, with the function | 3105 posix_trace_open( ). | 3106 When a trace event is reported it is possible to retrieve the following: | 3107 * A trace event type identifier | 3108 * A timestamp | 3109 * The process ID of the traced process, if the trace event is process-dependent | 3110 * Any optional trace event data including its length | 3111 * If the Threads option is supported, the thread ID, if the trace event is process-dependent | 3112 * The program address at which the trace point was invoked | 3113 3.408 Trace Event Type | 3114 A data object type that defines a class of trace event. A trace event type is identified on the one | 3115 hand by a trace event type name, also referenced as a trace event name, and on the other hand by | 3116 a trace event type identifier. A trace event name is a human-readable string. A trace event type | 3117 identifier is an opaque identifier used by the trace system. There is a one-to-one relationship | 3118 between trace event type identifiers and trace event names for a given trace stream and also for a | 3119 given traced process. The trace event type identifier is generated automatically from a trace | 3120 event name by the trace system either when a trace controller process invokes | 3121 posix_trace_trid_eventid_open( ) or when an instrumented application process invokes | 3122 posix_trace_eventid_open( ). Trace event type identifiers are used to filter trace event types, to | 3123 allow interpretation of user data, and to identify the kind of trace point that generated a trace | 3124 event. | 3125 3.409 Trace Event Type Mapping | 3126 A one-to-one mapping between trace event types and trace event names. One such mapping is | 3127 associated with each trace stream. An active trace stream is associated to a traced process, and | 3128 also to its children if the Trace Inherit option is supported and also the inheritance policy is set to | 3129 _POSIX_TRACE_INHERIT. Therefore each traced process has a mapping of the trace event | 3130 names to trace event type identifiers that have been defined for that process. | Base Definitions, Issue 6 111 Trace Filter Definitions 3131 3.410 Trace Filter | 3132 A filter that allows the trace controller process to specify those trace event types that are to be | 3133 ignored; that is, not generated. The operation of the filter is to filter out (ignore) selected trace | 3134 events. By default, no trace events are filtered. | 3135 3.411 Trace Generation Version | 3136 A data object that is an implementation-defined character string, generated by the trace system | 3137 and describing the origin and version of the trace system. | 3138 3.412 Trace Log | 3139 The flushed image of a trace stream, if the trace stream is created with a trace log. The trace log | 3140 is recorded when the posix_trace_shutdown( ) operation is invoked or during tracing, depending | 3141 on the tracing strategy which is defined by a log policy. After the trace stream has been shut | 3142 down, the trace information can be retrieved from the associated trace log using the same | 3143 interface used to retrieve information from an active trace stream. | 3144 3.413 Trace Point | 3145 An action that may cause a trace event to be generated. This may be an implementation-defined | 3146 action such as a context switch, or an application-programmed action such as a call to a specific | 3147 operating system service (for example, fork( )) or a call to posix_trace_event( ). | 3148 3.414 Trace Stream | 3149 An opaque object that contains trace events plus internal data needed to interpret those trace | 3150 events. The implementation and format of a trace stream are unspecified. A trace stream need | 3151 not be and generally is not persistent. A trace stream may be either active or pre-recorded: | 3152 * An active trace stream is a trace stream that has been created and has not yet been shut | 3153 down. It can be of one of the two following classes: | 3154 1. An active trace stream without a trace log that was created with the posix_trace_create( ) | 3155 function | 3156 2. If the Trace Log option is supported, an active trace stream with a trace log that was | 3157 created with the posix_trace_create_withlog( ) function | 3158 * A pre-recorded trace stream is a trace stream that was opened from a trace log object using | 3159 the posix_trace_open( ) function. | 3160 An active trace stream can loop. This behavior means that when the resources allocated by the | 3161 trace system for the trace stream are exhausted, the trace system reuses the resources associated | 3162 with the oldest recorded trace events to record new trace events. | 3163 If the Trace Log option is supported, an active trace stream with a trace log can be flushed. This | 3164 operation causes the trace system to write trace events from the trace stream to the associated | 3165 trace log, following the defined policies or using an explicit function call. After this operation, | 3166 the trace system may reuse the resources associated with the flushed trace events. | 112 Technical Standard (2000) (Draft July 28, 2000) Definitions Trace Stream 3167 An active trace stream with or without a trace log can be cleared. This operation causes all the | 3168 resources associated with this trace stream to be reinitialized. The trace stream behaves as if it | 3169 was returning from its creation, except that the mapping of trace event type identifiers to trace | 3170 event names is not cleared. If a trace log was associated with this trace stream, the trace log is | 3171 also reinitialized. | 3172 3.415 Trace Stream Identifier | 3173 A handle to manage tracing operations in a trace stream. | 3174 3.416 Trace System | 3175 A system that allows both system and user trace events to be generated into a trace stream. | 3176 These trace events can be retrieved later. | 3177 3.417 Traced Process | 3178 A process for which at least one trace stream has been created. A traced process is also called a | 3179 target process. If the Trace Inherit option is supported and the trace stream's inheritance | 3180 attribute is _POSIX_TRACE_INHERIT, the initial targeted traced process is traced together with | 3181 all of its future children. The posix_pid member of each trace event in a trace stream is the | 3182 process ID of the traced process. | 3183 3.418 Tracing Status of a Trace Stream | 3184 A status that describes the state of an active trace stream. The tracing status of a trace stream can | 3185 be retrieved from the trace stream attributes. An active trace stream can be in one of two states: | 3186 running or suspended. | 3187 3.419 Typed Memory Name Space 3188 A system-wide name space that contains the names of the typed memory objects present in the | 3189 system. It is configurable for a given implementation. | Base Definitions, Issue 6 113 Typed Memory Object Definitions 3190 3.420 Typed Memory Object 3191 A combination of a typed memory pool and a typed memory port. The entire contents of the | 3192 pool are accessible from the port. The typed memory object is identified through a name that | 3193 belongs to the typed memory name space. | 3194 3.421 Typed Memory Pool 3195 An extent of memory with the same operational characteristics. Typed memory pools may be | 3196 contained within each other. | 3197 3.422 Typed Memory Port 3198 A hardware access path to one or more typed memory pools. | 3199 3.423 Unbind 3200 Remove the association between a network address and an endpoint. | 3201 3.424 Unit Data 3202 See Datagram in Section 3.126 (on page 62). 3203 3.425 Upshifting 3204 The conversion of a lowercase character that has a single-character uppercase representation 3205 into this uppercase representation. 3206 3.426 User Database 3207 A system database of implementation-defined format that contains at least the following | 3208 information for each user ID: 3209 * User name 3210 * Numerical user ID 3211 * Initial numerical group ID 3212 * Initial working directory 3213 * Initial user program 3214 The initial numerical group ID is used by the newgrp utility. Any other circumstances under 3215 which the initial values are operative are implementation-defined. | 3216 If the initial user program field is null, an implementation-defined program is used. | 3217 If the initial working directory field is null, the interpretation of that field is implementation- | 3218 defined. | 114 Technical Standard (2000) (Draft July 28, 2000) Definitions User Database 3219 Note: The newgrp utility is defined in detail in the Shell and Utilities volume of | 3220 IEEE Std. 1003.1-200x. | 3221 3.427 User ID 3222 A non-negative integer that is used to identify a system user. When the identity of a user is 3223 associated with a process, a user ID value is referred to as a real user ID, an effective user ID, or a 3224 saved set-user-ID. 3225 3.428 User Name 3226 A string that is used to identify a user; see also Section 3.426 (on page 114). To be portable across | 3227 systems conforming to IEEE Std. 1003.1-200x, the value is composed of characters from the | 3228 portable file name character set. The hyphen should not be used as the first character of a 3229 portable user name. | 3230 3.429 User Trace Event | 3231 A trace event that is generated explicitly by the application as a result of a call to | 3232 posix_trace_event( ). | 3233 3.430 Utility 3234 A program, excluding special built-in utilities provided as part of the Shell Command Language, 3235 that can be called by name from a shell to perform a specific task, or related set of tasks. 3236 Note: For further information on special built-in utilities, see the Shell and Utilities volume | 3237 of IEEE Std. 1003.1-200x, Section 2.15, Special Built-In Utilities. | 3238 3.431 Variable 3239 In the shell command language, a named parameter. 3240 Note: For further information, see the Shell and Utilities volume of IEEE Std. 1003.1-200x, | 3241 Section 2.5, Parameters and Variables. | Base Definitions, Issue 6 115 Vertical-Tab Character () Definitions 3242 3.432 Vertical-Tab Character () 3243 A character that in the output stream indicates that printing should start at the next vertical 3244 tabulation position. The character is the character designated by '\v' in the C | 3245 language. If the current position is at or past the last defined vertical tabulation position, the 3246 behavior is unspecified. It is unspecified whether this character is the exact sequence transmitted 3247 to an output device by the system to accomplish the tabulation. 3248 3.433 White Space 3249 A sequence of one or more characters that belong to the space character class as defined via the 3250 LC_CTYPE category in the current locale. 3251 In the POSIX locale, white space consists of one or more characters ( and 3252 characters), characters, characters, characters, and 3253 characters. 3254 3.434 Wide-Character Code (C Language) 3255 An integer value corresponding to a single graphic symbol or control code. 3256 Note: C Language Wide-Character Codes are defined in detail in Section 6.3 (on page 137). 3257 3.435 Wide-Character Input/Output Functions 3258 The functions that perform wide-oriented input from streams or wide-oriented output to 3259 streams: fgetwc( ), fputwc( ), fputws( ), fwprintf( ), fwscanf( ), getwc( ), getwchar( ), getws( ), putwc( ), 3260 putwchar( ), ungetwc( ), vfwprintf( ), vwprintf( ), wprintf( ), and wscanf( ). 3261 Note: These functions are defined in detail in the System Interfaces volume of 3262 IEEE Std. 1003.1-200x. 3263 3.436 Wide-Character String 3264 A contiguous sequence of wide-character codes terminated by and including the first null wide- 3265 character code. 116 Technical Standard (2000) (Draft July 28, 2000) Definitions Word 3266 3.437 Word 3267 In the shell command language, a token other than an operator. In some cases a word is also a 3268 portion of a word token: in the various forms of parameter expansion, such as ${name-word}, and 3269 variable assignment, such as name=word, the word is the portion of the token depicted by word. 3270 The concept of a word is no longer applicable following word expansions-only fields remain. 3271 Note: For further information, see the Shell and Utilities volume of IEEE Std. 1003.1-200x, | 3272 Section 2.6.2, Parameter Expansion and the Shell and Utilities volume of | 3273 IEEE Std. 1003.1-200x, Section 2.6, Word Expansions. | 3274 3.438 Working Directory (or Current Working Directory) 3275 A directory, associated with a process, that is used in path name resolution for path names that 3276 do not begin with a slash. 3277 3.439 Worldwide Portability Interface 3278 Functions for handling characters in a codeset-independent manner. 3279 3.440 Write 3280 To output characters to a file, such as standard output or standard error. Unless otherwise 3281 stated, standard output is the default output destination for all uses of the term write; see the | 3282 distinction between display and write in Section 3.135 (on page 64). | 3283 3.441 XSI 3284 The X/Open System Interface is the core application programming interface for C and sh 3285 programming for systems conforming to the Single UNIX Specification. This is a superset of the 3286 mandatory requirements for conformance to IEEE Std. 1003.1-200x. | 3287 3.442 XSI-Conformant 3288 A system which allows an application to be built using a set of services that are consistent across 3289 all systems that conform to IEEE Std. 1003.1-200x and that support the XSI extension. 3290 Note: See also Chapter 2 (on page 19). Base Definitions, Issue 6 117 Zombie Process Definitions 3291 3.443 Zombie Process 3292 A process that has terminated and that is deleted when its exit status has been reported to | 3293 another process which is waiting for that process to terminate. | 3294 3.444 ±0 3295 The algebraic sign provides additional information about any variable that has the value zero 3296 when the representation allows the sign to be determined. 3297 CHANGE HISTORY 3298 Issue 4 3299 Numerous changes and additions are made for alignment with the ISO C standard and 3300 the ISO POSIX-1 standard. 3301 Issue 4, Version 2 3302 The following terms are added to support the adoption of additional traditional UNIX 3303 interfaces: alternate signal stack, break value, data segment, driver, hard limit, host byte 3304 order, named STREAM, network byte order, network host database, network net database, 3305 network protocol database, network service database, pad, parent window, priority band, 3306 process virtual time, pseudo-terminal, real time, signal stack, socket, soft limit, STREAM 3307 (second definition), STREAM end, STREAM head, STREAMS multiplexor, symbolic link, 3308 system console, and timer. 3309 Issue 5 3310 Numerous terms are added to support adoption of the POSIX Threads Extension and 3311 the POSIX Realtime Extension. 3312 Issue 6 3313 Additional terms are added to cover material from the ISO POSIX-1: 1996 standard and 3314 the ISO POSIX-2: 1993 standard not previously included. 3315 Various XSI-related terms are added. 3316 The following definitions are added for alignment with IEEE Std. 1003.1d-1999: Spawn, 3317 Timeouts, Execution Time Monitoring, Sporadic Server, Advisory Information, CPU 3318 Time, CPU-Time Clock, CPU-Time Timer, and Execution Time. 3319 The definition of Memory Object is modified to include typed memory objects for 3320 alignment with IEEE Std. 1003.1j-2000. 3321 Definitions of Barrier, Clock Jump, Monotonic Clock, Read-Write Lock, Spin Lock, | 3322 Typed Memory Name Space, Typed Memory Object, Typed Memory Pool, and Typed 3323 Memory Port are added for alignment with IEEE Std. 1003.1j-2000. 3324 The Read-Write Lock definition is moved under the RWL option for alignment with 3325 IEEE Std. 1003.1j-2000. 118 Technical Standard (2000) (Draft July 28, 2000) Definitions ±0 3326 Notes to Reviewers 3327 This section with side shading will not appear in the final copy. - Ed. 3328 To be further expanded. Base Definitions, Issue 6 119 Definitions 3329 | 120 Technical Standard (2000) (Draft July 28, 2000) Chapter 4 General Concepts 3330 3331 4.1 Concurrent Execution | 3332 Functions that suspend the execution of the calling thread shall not cause the execution of other | 3333 threads to be indefinitely suspended. | 3334 4.2 Extended Security Controls | 3335 An implementation may provide implementation-defined extended security controls (see | 3336 Section 3.161 (on page 68)). These permit an implementation to provide security mechanisms to | 3337 implement different security policies than those described in IEEE Std. 1003.1-200x. These | 3338 mechanisms shall not alter or override the defined semantics of any of the interfaces in | 3339 IEEE Std. 1003.1-200x. | 3340 4.3 File Access Permissions 3341 The standard file access control mechanism uses the file permission bits, as described below. 3342 Implementations may provide additional or alternate file access control mechanisms, or both. An 3343 additional access control mechanism shall only further restrict the access permissions defined by | 3344 the file permission bits. An alternate file access control mechanism shall: | 3345 * Specify file permission bits for the file owner class, file group class, and file other class of that | 3346 file, corresponding to the access permissions. 3347 * Be enabled only by explicit user action, on a per-file basis by the file owner or a user with the | 3348 appropriate privilege. 3349 * Be disabled for a file after the file permission bits are changed for that file with chmod( ). The | 3350 disabling of the alternate mechanism need not disable any additional mechanisms supported 3351 by an implementation. 3352 Whenever a process requests file access permission for read, write, or execute/search, if no 3353 additional mechanism denies access, access is determined as follows: 3354 * If a process has the appropriate privilege: 3355 - If read, write, or directory search permission is requested, access is granted. 3356 - If execute permission is requested, access is granted if execute permission is granted to at 3357 least one user by the file permission bits or by an alternate access control mechanism; 3358 otherwise, access is denied. 3359 * Otherwise: 3360 - The file permission bits of a file contain read, write, and execute/search permissions for 3361 the file owner class, file group class, and file other class. 3362 - Access is granted if an alternate access control mechanism is not enabled and the 3363 requested access permission bit is set for the class (file owner class, file group class, or file 3364 other class) to which the process belongs, or if an alternate access control mechanism is Base Definitions, Issue 6 121 File Access Permissions General Concepts 3365 enabled and it allows the requested access; otherwise, access is denied. 3366 4.4 File Hierarchy | 3367 Files in the system are organized in a hierarchical structure in which all of the non-terminal | 3368 nodes are directories and all of the terminal nodes are any other type of file. Because multiple | 3369 directory entries may refer to the same file, the hierarchy is properly described as a directed | 3370 graph. | 3371 4.5 File Names 3372 For a file name to be portable across implementations conforming to IEEE Std. 1003.1-200x, it 3373 shall consist only of the Portable File Name Character Set as defined in Section 3.278 (on page 3374 88). 3375 The hyphen character shall not be used as the first character of a portable file name. Uppercase 3376 and lowercase letters retain their unique identities between conforming implementations. In the 3377 case of a portable path name, the slash character may also be used. 3378 4.6 File Times Update 3379 Each file has three distinct associated time values: st_atime, st_mtime, and st_ctime. The st_atime 3380 field is associated with the times that the file data is accessed; st_mtime is associated with the 3381 times that the file data is modified; and st_ctime is associated with the times that the file status is 3382 changed. These values are returned in the file characteristics structure, as described in 3383 . 3384 Each function or utility in IEEE Std. 1003.1-200x that reads or writes data or changes file status 3385 indicates which of the appropriate time-related fields shall be ``marked for update''. If an 3386 implementation of such a function or utility marks for update a time-related field not specified 3387 by IEEE Std. 1003.1-200x, this shall be documented, except that any changes caused by path 3388 name resolution need not be documented. For the other functions or utilities in 3389 IEEE Std. 1003.1-200x (those that are not explicitly required to read or write file data or change 3390 file status, but that in some implementations happen to do so), the effect is unspecified. 3391 An implementation may update fields that are marked for update immediately, or it may update 3392 such fields periodically. At an update point in time, any marked fields are set to the current time 3393 and the update marks are cleared. All fields that are marked for update shall be updated when 3394 the file ceases to be open by any process, or when a stat( ), fstat( ), or lstat( ) is performed on the 3395 file. Other times at which updates are done are unspecified. Marks for update, and updates 3396 themselves, are not done for files on read-only file systems; see Section 3.306 (on page 93). 122 Technical Standard (2000) (Draft July 28, 2000) General Concepts Measurement of Execution Time 3397 4.7 Measurement of Execution Time 3398 The mechanism used to measure execution time shall be implementation-defined. The | 3399 implementation shall also define to whom the CPU time that is consumed by interrupt handlers | 3400 and system services on behalf of the operating system will be charged. See Section 3.120 (on | 3401 page 62). | 3402 4.8 Memory Synchronization | 3403 Applications shall ensure that access to any memory location by more than one thread of control | 3404 (threads or processes) is restricted such that no thread of control can read or modify a memory | 3405 location while another thread of control may be modifying it. Such access is restricted using | 3406 functions that synchronize thread execution and also synchronize memory with respect to other | 3407 threads. The following functions synchronize memory with respect to other threads: | 3408 fork( ) pthrea | d_mutex_trylock( ) | || || || 3409 pthread_cond_broadcast( ) pthrea | d_mutex_unlock( ) | || || 3410 pthread_cond_signal( ) | sem_post( ) | || || 3411 pthread_cond_timedwait( ) | sem_trywait( ) | || || 3412 pthread_cond_wait( ) | sem_wait( ) | || || 3413 pthread_create( ) wait( )| | || || 3414 pthread_join( ) | waitpid( ) | || || 3415 pthread_mutex_lock( ) | || 3416 Notes to Reviewers | 3417 This section with side shading will not appear in the final copy. - Ed. | 3418 We need to check whether there should be any additional functions listed. | 3419 Unless explicitly stated otherwise, if one of the above functions returns an error, it is unspecified | 3420 whether the invocation causes memory to be synchronized. | 3421 Applications may allow more than one thread of control to read a memory location | 3422 simultaneously. | 3423 4.9 Path Name Resolution 3424 Path name resolution is performed for a process to resolve a path name to a particular file in a 3425 file hierarchy. There may be multiple path names that resolve to the same file. 3426 Each file name in the path name is located in the directory specified by its predecessor (for 3427 example, in the path name fragment a/b, file b is located in directory a). Path name resolution 3428 fails if this cannot be accomplished. If the path name begins with a slash, the predecessor of the 3429 first file name in the path name is taken to be the root directory of the process (such path names 3430 are referred to as absolute path names). If the path name does not begin with a slash, the 3431 predecessor of the first file name of the path name is taken to be the current working directory of 3432 the process (such path names are referred to as relative path names). 3433 The interpretation of a path name component is dependent on the value of {NAME_MAX} and | 3434 _POSIX_NO_TRUNC associated with the path prefix of that component. If any path name | 3435 component is longer than {NAME_MAX}, the implementation shall consider this an error. | 3436 A path name that contains at least one non-slash character and that ends with one or more 3437 trailing slashes shall be resolved as if a single dot character ('.') were appended to the path Base Definitions, Issue 6 123 Path Name Resolution General Concepts 3438 name. 3439 If a symbolic link is encountered during path name resolution, the behavior shall depend on 3440 whether the path name component is at the end of the path name and on the function being 3441 performed. If all of the following are true, then path name resolution is complete: 3442 1. This is the last path name component of the path name. 3443 2. The path name has no trailing slash. 3444 3. The function is required to act on the symbolic link itself, or certain arguments direct that 3445 the function act on the symbolic link itself. 3446 In all other cases, the system shall prefix the remaining path name, if any, with the contents of 3447 the symbolic link. If the combined length exceeds {PATH_MAX}, and the implementation 3448 considers this to be an error, errno shall be set to [ENAMETOOLONG] and an error indication 3449 shall be returned. Otherwise, the resolved path name shall be the resolution of the path name 3450 just created. If the resulting path name does not begin with a slash, the predecessor of the first 3451 file name of the path name is taken to be the directory containing the symbolic link. 3452 If the system detects a loop in the path name resolution process, it shall set errno to [ELOOP] and | 3453 return an error indication. The same may happen if during the resolution process more symbolic | 3454 links were followed than the implementation allows. This implementation-defined limit shall | 3455 not be smaller than {SYMLOOP_MAX}. | 3456 The special file name dot refers to the directory specified by its predecessor. The special file | 3457 name dot-dot refers to the parent directory of its predecessor directory. As a special case, in the 3458 root directory, dot-dot may refer to the root directory itself. 3459 A path name consisting of a single slash resolves to the root directory of the process. A null path 3460 name shall not be successfully resolved. A path name that begins with two successive slashes | 3461 may be interpreted in an implementation-defined manner, although more than two leading | 3462 slashes shall be treated as a single slash. | 3463 4.10 Process ID Reuse 3464 A process group ID shall not be reused by the system until the process group lifetime ends. 3465 A process ID shall not be reused by the system until the process lifetime ends. In addition, if 3466 there exists a process group whose process group ID is equal to that process ID, the process ID 3467 shall not be reused by the system until the process group lifetime ends. A process that is not a 3468 system process shall not have a process ID of 1. | 124 Technical Standard (2000) (Draft July 28, 2000) General Concepts Scheduling Policy 3469 4.11 Scheduling Policy | 3470 A scheduling policy affects process or thread ordering: | 3471 * When a process or thread is a running thread and it becomes a blocked thread | 3472 * When a process or thread is a running thread and it becomes a preempted thread | 3473 * When a process or thread is a blocked thread and it becomes a runnable thread | 3474 * When a running thread calls a function that can change the priority or scheduling policy of a | 3475 process or thread | 3476 * In other scheduling policy-defined circumstances | 3477 Conforming implementations are required to define the manner in which each of the scheduling | 3478 policies may modify the priorities or otherwise affect the ordering of processes or threads at | 3479 each of the occurrences listed above. Additionally, conforming implementations define in what | 3480 other circumstances and in what manner each scheduling policy may modify the priorities or | 3481 affect the ordering of processes or threads. | 3482 4.12 Seconds Since the Epoch | 3483 A value that approximates the number of seconds that have elapsed since the Epoch. A | 3484 Coordinated Universal Time name (specified in terms of seconds (tm_sec), minutes (tm_min), | 3485 hours (tm_hour), days since January 1 of the year (tm_yday), and calendar year minus 1900 | 3486 (tm_year)) is related to a time represented as seconds since the Epoch, according to the | 3487 expression below. | 3488 If the year is <1970 or the value is negative, the relationship is undefined. If the year is 1970 and | 3489 the value is non-negative, the value is related to a Coordinated Universal Time name according | 3490 to the C-language expression, where tm_sec, tm_min, tm_hour, tm_yday, and tm_year are all | 3491 integer types: | 3492 tm_sec + tm_min*60 + tm_hour*3600 + tm_yday*86400 + || 3493 (tm_year-70)*31536000 + ((tm_year-69)/4)*86400 - || 3494 ((tm_year-1/100)*86400 + ((tm_year+299)/400)*86400 || 3495 Whether and how the implementation accounts for leap seconds is unspecified. | 3496 Note: The last term of the current expression adds in a day for every 4th year starting in | 3497 1973. (January 1st of each year following a leap year starting with the first leap year | 3498 after 1970). The first term above subtracts a day every 100 years starting in 2001. The | 3499 last term above adds a day back in every 400 years starting in 2001. | Base Definitions, Issue 6 125 Semaphore General Concepts 3500 4.13 Semaphore | 3501 A minimum synchronization primitive to serve as a basis for more complex synchronization | 3502 mechanisms to be defined by the application program. | 3503 For the semaphores associated with the Semaphores option, a semaphore is represented as a | 3504 shareable resource that has a non-negative integral value. When the value is zero, there is a | 3505 (possibly empty) set of threads awaiting the availability of the semaphore. | 3506 For the semaphores associated with the X/Open System Interface Extension (XSI), a semaphore | 3507 is a positive integer (0 through 32767). The semget( ) function can be called to create a set or array | 3508 of semaphores. A semaphore set can contain one or more semaphores up to an implementation- | 3509 defined value. | 3510 Semaphore Lock Operation | 3511 An operation that is applied to a semaphore. If, prior to the operation, the value of the | 3512 semaphore is zero, the semaphore lock operation shall cause the calling thread to be blocked and | 3513 added to the set of threads awaiting the semaphore; otherwise, the value is decremented. | 3514 Semaphore Unlock Operation | 3515 An operation that is applied to a semaphore. If, prior to the operation, there are any threads in | 3516 the set of threads awaiting the semaphore, then some thread from that set shall be removed from | 3517 the set and becomes unblocked; otherwise, the semaphore value is incremented. | 3518 4.14 Thread-Safety | 3519 Refer to the System Interfaces volume of IEEE Std. 1003.1-200x, Section 2.9, Threads. | 3520 4.15 Utility 3521 A utility program shall be either an executable file, such as might be produced by a compiler or 3522 linker system from computer source code, or a file of shell source code, directly interpreted by 3523 the shell. The program may have been produced by the user, provided by the system 3524 implementor, or acquired from an independent distributor. 3525 The system may implement certain utilities as shell functions (see the Shell and Utilities volume | 3526 of IEEE Std. 1003.1-200x, Section 2.9.5, Function Definition Command) or built-in utilities, but | 3527 only an application that is aware of the command search order described in the Shell and | 3528 Utilities volume of IEEE Std. 1003.1-200x, Section 2.9.1.1, Command Search and Execution or of | 3529 performance characteristics can discern differences between the behavior of such a function or | 3530 built-in utility and that of an executable file. | 126 Technical Standard (2000) (Draft July 28, 2000) General Concepts Variable Assignment 3531 4.16 Variable Assignment | 3532 In the shell command language, a word consisting of the following parts: | 3533 varname=value || 3534 When used in a context where assignment is defined to occur and at no other time, the value | 3535 (representing a word or field) shall be assigned as the value of the variable denoted by varname. | 3536 Note: For further information, see the Shell and Utilities volume of IEEE Std. 1003.1-200x, | 3537 Section 2.9.1, Simple Commands. | 3538 The varname and value parts meet the requirements for a name and a word, respectively, except | 3539 that they are delimited by the embedded unquoted equals-sign, in addition to other delimiters. | 3540 Note: Additional delimiters are described in the Shell and Utilities volume of | 3541 IEEE Std. 1003.1-200x, Section 2.3, Token Recognition. | 3542 When a variable assignment is done, the variable shall be created if it did not already exist. If | 3543 value is not specified, the variable shall be given a null value. | 3544 Note: An alternative form of variable assignment: | 3545 symbol=value || 3546 (where symbol is a valid word delimited by an equals-sign, but not a valid name) | 3547 produces unspecified results. The form symbol=value is used by the KornShell | 3548 name[expression]=value syntax. | Base Definitions, Issue 6 127 General Concepts | 3549 | 128 Technical Standard (2000) (Draft July 28, 2000) Chapter 5 File Format Notation 3550 3551 The STDIN, STDOUT, STDERR, INPUT FILES, and OUTPUT FILES sections of the utility 3552 descriptions use a syntax to describe the data organization within the files, when that 3553 organization is not otherwise obvious. The syntax is similar to that used by the System Interfaces 3554 volume of IEEE Std. 1003.1-200x printf( ) function, as described in this chapter. When used in 3555 STDIN or INPUT FILES sections of the utility descriptions, this syntax describes the format that 3556 could have been used to write the text to be read, not a format that could be used by the System 3557 Interfaces volume of IEEE Std. 1003.1-200x scanf( ) function to read the input file. 3558 The description of an individual record is as follows: 3559 "", [, ,..., ] | 3560 The format is a character string that contains three types of objects defined below: 3561 1. Characters that are not escape sequences or conversion specifications, as described below, shall 3562 be copied to the output. 3563 2. Escape Sequences represent non-graphic characters. 3564 3. Conversion Specifications specify the output format of each argument; (see below). 3565 The following characters have the following special meaning in the format string: 3566 ' ' (An empty character position.) Represents one or more characters. 3567 Represents exactly one character. 3568 Table 5-1 lists escape sequences and associated actions on display devices capable of the action. Base Definitions, Issue 6 129 File Format Notation 3569 Table 5-1 Escape Sequences and Associated Actions ___________________________________________________________________________________ | 3570 Escape Represents | 3571 Sequence Character Terminal Action | ___________________________________________________________________________________ | 3572 '\\' backslash P|rint the character '\'. | ||| 3573 '\a' alert | Attempts to alert the user through audible or visible notification. | ||| 3574 '\b' backspace | Moves the printing position to one column before the current | ||| 3575 position, unless the current position is the start of a line. | | 3576 '\f' form-feed | Moves the printing position to the initial printing position of the | ||| 3577 next logical page. | | 3578 '\n' newline | Moves the printing position to the start of the next line. | ||| 3579 '\r' carriage-return | Moves the printing position to the start of the current line. | ||| 3580 '\t' tab | Moves the printing position to the next tab position on the | ||| 3581 current line. If there are no more tab positions remaining on the | | 3582 line, the behavior is undefined. | | 3583 '\v' vertical-tab | Moves the printing position to the start of the next vertical tab | ||| 3584 position. If there are no more vertical tab positions left on the | | 3585 page, the behavior is undefined. | | _ __________________________________________________________________________________ ||||| 3586 Each conversion specification shall be introduced by the percent-sign character ('%'). After the 3587 character '%', the following shall appear in sequence: 3588 flags Zero or more flags, in any order, that modify the meaning of the conversion 3589 specification. 3590 field width An optional string of decimal digits to specify a minimum field width. For an 3591 output field, if the converted value has fewer bytes than the field width, it shall be 3592 padded on the left (or right, if the left-adjustment flag ('-'), described below, has 3593 been given) to the field width. 3594 precision Gives the minimum number of digits to appear for the d, o, i, u, x, or X conversions 3595 (the field is padded with leading zeros), the number of digits to appear after the 3596 radix character for the e and f conversions, the maximum number of significant 3597 digits for the g conversion; or the maximum number of bytes to be written from a 3598 string in s conversion. The precision shall take the form of a period ('.') followed 3599 by a decimal digit string; a null digit string is treated as zero. 3600 conversion characters 3601 A conversion character (see below) that indicates the type of conversion to be 3602 applied. 3603 The flag characters and their meanings are: 3604 - The result of the conversion shall be left-justified within the field. 3605 + The result of a signed conversion shall always begin with a sign ('+' or '-'). 3606 If the first character of a signed conversion is not a sign, a character shall 3607 be prefixed to the result. This means that if the character and '+' flags 3608 both appear, the character flag shall be ignored. 3609 # The value is to be converted to an alternative form. For c, d, i, u, and s conversions, 3610 the behavior is undefined. For o conversion, it shall increase the precision to force 3611 the first digit of the result to be a zero. For x or X conversion, a non-zero result has 3612 0x or 0X prefixed to it, respectively. For e, E, f, g, and G conversions, the result shall 3613 always contain a radix character, even if no digits follow the radix character. For g 130 Technical Standard (2000) (Draft July 28, 2000) File Format Notation 3614 and G conversions, trailing zeros shall not be removed from the result as they 3615 usually are. 3616 0 For d, i, o, u, x, X, e, E, f, g, and G conversions, leading zeros (following any 3617 indication of sign or base) shall be used to pad to the field width; no space padding 3618 is performed. If the '0' and '-' flags both appear, the '0' flag shall be ignored. 3619 For d, i, o, u, x, and X conversions, if a precision is specified, the '0' flag shall be 3620 ignored. For other conversions, the behavior is undefined. 3621 Each conversion character shall result in fetching zero or more arguments. The results are 3622 undefined if there are insufficient arguments for the format. If the format is exhausted while 3623 arguments remain, the excess arguments shall be ignored. 3624 The conversion characters and their meanings are: 3625 d,i,o,u,x,X The integer argument shall be written as signed decimal (d or i), unsigned octal (o), 3626 unsigned decimal (u), or unsigned hexadecimal notation (x and X). The d and i 3627 specifiers shall convert to signed decimal in the style [-]dddd. The x conversion 3628 shall use the numbers and letters 0123456789abcdef and the X conversion shall use 3629 the numbers and letters 0123456789ABCDEF. The precision component of the 3630 argument shall specify the minimum number of digits to appear. If the value being 3631 converted can be represented in fewer digits than the specified minimum, it shall 3632 be expanded with leading zeros. The default precision shall be 1. The result of 3633 converting a zero value with a precision of 0 shall be no characters. If both the field 3634 width and precision are omitted, the implementation may precede, follow, or 3635 precede and follow numeric arguments of types d, i, and u with 3636 characters; arguments of type o (octal) may be preceded with leading zeros. 3637 f The floating point number argument shall be written in decimal notation in the 3638 style [-]ddd.ddd, where the number of digits after the radix character (shown here 3639 as a decimal point) shall be equal to the precision specification. The LC_NUMERIC 3640 locale category shall determine the radix character to use in this format. If the 3641 precision is omitted from the argument, six digits shall be written after the radix 3642 character; if the precision is explicitly 0, no radix character shall appear. 3643 e,E The floating point number argument shall be written in the style [-]d.ddd±dd (the 3644 symbol '±' indicates either a plus or minus sign), where there is one digit before 3645 the radix character (shown here as a decimal point) and the number of digits after 3646 it is equal to the precision. The LC_NUMERIC locale category shall determine the 3647 radix character to use in this format. When the precision is missing, six digits shall 3648 be written after the radix character; if the precision is 0, no radix character shall 3649 appear. The E conversion character shall produce a number with E instead of e 3650 introducing the exponent. The exponent shall always contain at least two digits. 3651 However, if the value to be written requires an exponent greater than two digits, 3652 additional exponent digits shall be written as necessary. 3653 g,G The floating point number argument shall be written in style f or e (or in style E in 3654 the case of a G conversion character), with the precision specifying the number of 3655 significant digits. The style used depends on the value converted: style e (or E) 3656 shall be used only if the exponent resulting from the conversion is less than -4 or 3657 greater than or equal to the precision. Trailing zeros are removed from the result. A 3658 radix character shall appear only if it is followed by a digit. 3659 c The integer argument shall be converted to an unsigned char and the resulting 3660 byte shall be written. Base Definitions, Issue 6 131 File Format Notation 3661 s The argument shall be taken to be a string and bytes from the string shall be 3662 written until the end of the string or the number of bytes indicated by the precision 3663 specification of the argument is reached. If the precision is omitted from the 3664 argument, it shall be taken to be infinite, so all bytes up to the end of the string 3665 shall be written. 3666 % Write a '%' character; no argument is converted. 3667 In no case does a nonexistent or insufficient field width cause truncation of a field; if the result of 3668 a conversion is wider than the field width, the field is simply expanded to contain the conversion 3669 result. The term field width should not be confused with the term precision used in the description 3670 of %s. | 3671 Examples | 3672 To represent the output of a program that prints a date and time in the form Sunday, July 3, 3673 10:02, where weekday and month are strings: 3674 "%s, %s %d, %d:%.2d\n" , , , , | 3675 To show ' ' written to 5 decimal places: 3676 "pi = %.5f\n", | 3677 To show an input file format consisting of five colon-separated fields: 3678 "%s:%s:%s:%s:%s\n", , , , , || 3679 | 132 Technical Standard (2000) (Draft July 28, 2000) Chapter 6 Character Set 3680 3681 6.1 Portable Character Set 3682 Conforming implementations shall support one or more coded character sets. Each supported 3683 locale shall include the portable character set, which is the set of symbolic names for characters in | 3684 Table 6-1. This is used to describe characters within the text of IEEE Std. 1003.1-200x. The first | 3685 eight entries in Table 6-1 are defined in the ISO/IEC 6429: 1992 standard and the rest of the | 3686 characters are defined in the ISO/IEC 10646-1: 1993 standard. | 3687 Table 6-1 Portable Character Set 3688 _____________________________________________________________________________ 3689 _ Symbolic Name Glyph UCS Description ____________________________________________________________________________ 3690 NULL (NUL) 3691 BELL (BEL) 3692 BACKSPACE (BS) 3693 CHARACTER TABULATION (HT) 3694 CARRIAGE RETURN (CR) 3695 LINE FEED (LF) 3696 LINE TABULATION (VT) 3697 FORM FEED (FF) 3698 SPACE 3699 ! EXCLAMATION MARK 3700 " QUOTATION MARK 3701 # NUMBER SIGN 3702 $ DOLLAR SIGN 3703 % PERCENT SIGN 3704 & AMPERSAND 3705 ' APOSTROPHE 3706 ( LEFT PARENTHESIS 3707 ) RIGHT PARENTHESIS 3708 * ASTERISK 3709 + PLUS SIGN 3710 , COMMA 3711 - HYPHEN-MINUS 3712 - HYPHEN-MINUS 3713 . FULL STOP 3714 . FULL STOP 3715 / SOLIDUS 3716 / SOLIDUS 3717 0 DIGIT ZERO 3718 1 DIGIT ONE 3719 2 DIGIT TWO 3720 _ 3 DIGIT THREE ____________________________________________________________________________ Base Definitions, Issue 6 133 Portable Character Set Character Set 3721 _____________________________________________________________________________ 3722 _ Symbolic Name Glyph UCS Description ____________________________________________________________________________ 3723 4 DIGIT FOUR 3724 5 DIGIT FIVE 3725 6 DIGIT SIX 3726 7 DIGIT SEVEN 3727 8 DIGIT EIGHT 3728 9 DIGIT NINE 3729 : COLON 3730 ; SEMICOLON 3731 < LESS-THAN SIGN 3732 = EQUALS SIGN 3733 > GREATER-THAN SIGN 3734 ? QUESTION MARK 3735 @ 3736 A LATIN CAPITAL LETTER A 3737 B LATIN CAPITAL LETTER B 3738 C LATIN CAPITAL LETTER C 3739 D LATIN CAPITAL LETTER D 3740 E LATIN CAPITAL LETTER E 3741 F LATIN CAPITAL LETTER F 3742 G LATIN CAPITAL LETTER G 3743 H LATIN CAPITAL LETTER H 3744 I LATIN CAPITAL LETTER I 3745 J LATIN CAPITAL LETTER J 3746 K LATIN CAPITAL LETTER K 3747 L LATIN CAPITAL LETTER L 3748 M LATIN CAPITAL LETTER M 3749 N LATIN CAPITAL LETTER N 3750 O LATIN CAPITAL LETTER O 3751

p LATIN SMALL LETTER P 3789 q LATIN SMALL LETTER Q 3790 r LATIN SMALL LETTER R 3791 s LATIN SMALL LETTER S 3792 t LATIN SMALL LETTER T 3793 u LATIN SMALL LETTER U 3794 v LATIN SMALL LETTER V 3795 w LATIN SMALL LETTER W 3796 x LATIN SMALL LETTER X 3797 y LATIN SMALL LETTER Y 3798 z LATIN SMALL LETTER Z 3799 { LEFT CURLY BRACKET 3800 { LEFT CURLY BRACKET 3801 | VERTICAL LINE 3802 } RIGHT CURLY BRACKET 3803 } RIGHT CURLY BRACKET 3804 _ ~ TILDE ____________________________________________________________________________ 3805 IEEE Std. 1003.1-200x uses other character names than the above, but only in an informative | 3806 way; for example, in examples to illustrate the use of characters beyond the portable character | 3807 set with the facilities of IEEE Std. 1003.1-200x. | 3808 Table 6-1 (on page 133) defines the characters in the portable character set and the corresponding | 3809 symbolic character names used to identify each character in a character set description file. The 3810 table contains more than one symbolic character name for characters whose traditional name 3811 differs from the chosen name. 3812 IEEE Std. 1003.1-200x places only the following requirements on the encoded values of the 3813 characters in the portable character set: 3814 * If the encoded values associated with each member of the portable character set are not 3815 invariant across all locales supported by the implementation, the results achieved by an 3816 application accessing those locales are unspecified. 3817 * The encoded values associated with the digits 0 to 9 shall be such that the value of each 3818 character after 0 shall be one greater than the value of the previous character. Base Definitions, Issue 6 135 Portable Character Set Character Set 3819 * A null character, NUL, which has all bits set to zero, shall be in the set of characters. 3820 * The encoded values associated with the members of the portable character set are each 3821 represented in a single byte. Moreover, if the value is stored in an object of C-language type 3822 char, it is guaranteed to be positive (except the NUL, which is always zero). 3823 Conforming implementations shall support certain character and character set attributes, as 3824 defined in Section 7.2 (on page 144). | 3825 6.2 Character Encoding 3826 The POSIX locale contains the characters in Table 6-1 (on page 133), which have the properties 3827 listed in Section 7.3.1 (on page 147). Implementations may also add other characters. In other 3828 locales, the presence, meaning, and representation of any additional characters is locale-specific. 3829 In locales other than the POSIX locale, a character may have a state-dependent encoding. There 3830 are two types of these encodings: 3831 * A single-shift encoding (where each character not in the initial shift state is preceded by a 3832 shift code) can be defined if each shift-code and character sequence is considered a multi- 3833 byte character. This is done using the concatenated-constant format in a character set 3834 description file, as described in Section 6.4 (on page 137). If the implementation supports a 3835 character encoding of this type, all of the standard utilities in the Shell and Utilities volume of | 3836 IEEE Std. 1003.1-200x support it. Use of a single-shift encoding with any of the functions in | 3837 the System Interfaces volume of IEEE Std. 1003.1-200x that do not specifically mention the 3838 effects of state-dependent encoding is implementation-defined. | 3839 * A locking-shift encoding (where the state of the character is determined by a shift code that 3840 may affect more than the single character following it) cannot be defined with the current 3841 character set description file format. Use of a locking-shift encoding with any of the standard | 3842 utilities in the Shell and Utilities volume of IEEE Std. 1003.1-200x or with any of the functions | 3843 in the System Interfaces volume of IEEE Std. 1003.1-200x that do not specifically mention the | 3844 effects of state-dependent encoding is implementation-defined. | 3845 While in the initial shift state, all characters in the portable character set retain their usual 3846 interpretation and do not alter the shift state. The interpretation for subsequent bytes in the 3847 sequence is a function of the current shift state. A byte with all bits zero is interpreted as the null 3848 character independent of shift state. Thus a byte with all bits zero shall never occur in the second 3849 or subsequent bytes of a character. 3850 The maximum allowable number of bytes in a character in the current locale is indicated by 3851 {MB_CUR_MAX}, defined in the header and by the value in a 3852 character set description file; see Section 6.4 (on page 137). The implementation's maximum 3853 number of bytes in a character is defined by the C-language macro {MB_LEN_MAX}. | 136 Technical Standard (2000) (Draft July 28, 2000) Character Set C Language Wide-Character Codes 3854 6.3 C Language Wide-Character Codes 3855 In the shell, the standard utilities are written so that the encodings of characters are described by 3856 the locale's LC_CTYPE definition (see Section 7.3.1 (on page 147)) and there is no differentiation 3857 between characters consisting of single octets (8-bit bytes), larger bytes, or multiple bytes. 3858 However, in the C language, a differentiation is made. To ease the handling of variable length 3859 characters, the C language has introduced the concept of wide-character codes. 3860 All wide-character codes in a given process consist of an equal number of bits. This is in contrast 3861 to characters, which can consist of a variable number of bytes. The byte or byte sequence that 3862 represents a character can also be represented as a wide-character code. Wide-character codes 3863 thus provide a uniform size for manipulating text data. A wide-character code having all bits 3864 zero is the null wide-character code (see Section 3.248 (on page 83)), and terminates wide- 3865 character strings (see Section 3.434 (on page 116)). The wide-character value for each member of 3866 the Portable Character Set equals its value when used as the lone character in an integer 3867 character constant. Wide-character codes for other characters are locale and implementation- | 3868 defined. State shift bytes do not have a wide-character code representation. | 3869 6.4 Character Set Description File 3870 Implementations shall provide a character set description file for at least one coded character set 3871 supported by the implementation. These files are referred to elsewhere in IEEE Std. 1003.1-200x 3872 as charmap files. It is implementation-defined whether or not users or applications can provide | 3873 additional character set description files. 3874 IEEE Std. 1003.1-200x does not require that multiple character sets or codesets be supported. 3875 Although multiple charmap files are supported, it is the responsibility of the implementation to 3876 provide the file or files; if only one is provided, only that one is accessible using the localedef 3877 utility's -f option. | 3878 Each character set description file, except those that use the ISO/IEC 10646-1: 1993 standard 3879 position values as the encoding values, shall define characteristics for the coded character set 3880 and the encoding for the characters specified in Table 6-1 (on page 133), and may define 3881 encoding for additional characters supported by the implementation. Other information about 3882 the coded character set may also be in the file. Coded character set character values shall be 3883 defined using symbolic character names followed by character encoding values. 3884 Each symbolic name specified in Table 6-1 (on page 133) shall be included in the file and shall be | 3885 mapped to a unique encoding value (except for those symbolic names that are shown with | 3886 identical glyphs). If the control characters commonly associated with the symbolic names in the | 3887 following table are supported by the implementation, the symbolic names and their | 3888 corresponding encoding values shall be included in the file. Some of the encodings associated | 3889 with the symbolic names in this table may be the same as characters in the portable character set | 3890 table. | 3891 Table 6-2 Control Character Set _________________________________________________________ | 3892 | 3893 | 3894 | 3895 | 3896 | 3897 | _________________________________________________________ ||| Base Definitions, Issue 6 137 Character Set Description File Character Set 3898 The following declarations can precede the character definitions. Each consists of the symbol 3899 shown in the following list, starting in column 1, including the surrounding brackets, followed 3900 by one or more characters, followed by the value to be assigned to the symbol. 3901 The name of the coded character set for which the character set 3902 description file is defined. The characters of the name shall be taken from 3903 the set of characters with visible glyphs defined in Table 6-1 (on page 3904 133). 3905 The maximum number of bytes in a multi-byte character. This defaults to 3906 1. 3907 An unsigned positive integer value that defines the minimum number of 3908 XSI bytes in a character for the encoded character set. On XSI-conformant 3909 systems, shall always be 1. | 3910 The escape character used to indicate that the characters following are 3911 interpreted in a special way, as defined later in this section. This defaults 3912 to backslash ('\'), which is the character glyph used in all the following 3913 text and examples, unless otherwise noted. 3914 The character that, when placed in column 1 of a charmap line, is used to 3915 indicate that the line is to be ignored. The default character is the number 3916 sign ('#'). 3917 The character set mapping definitions shall be all the lines immediately following an identifier 3918 line containing the string "CHARMAP" starting in column 1, and preceding a trailer line 3919 containing the string "END CHARMAP" starting in column 1. Empty lines and lines containing a 3920 in the first column shall be ignored. Each non-comment line of the character 3921 set mapping definition (that is, between the "CHARMAP" and "END CHARMAP" lines of the file) 3922 shall be in either of two forms: 3923 "%s %s %s\n", , , | 3924 or: 3925 "%s...%s %s %s\n", , , | 3926 , | 3927 In the first format, the line in the character set mapping definition defines a single symbolic 3928 name and a corresponding encoding. A symbolic name is one or more characters from the set 3929 shown with visible glyphs in Table 6-1 (on page 133), enclosed between angle brackets. A 3930 character following an escape character is interpreted as itself; for example, the sequence 3931 "<\\\>>" represents the symbolic name "\>" enclosed between angle brackets. 3932 In the second format, the line in the character set mapping definition defines a range of one or 3933 more symbolic names. In this form, the symbolic names shall consist of zero or more non- 3934 numeric characters from the set shown with visible glyphs in Table 6-1 (on page 133), followed 3935 by an integer formed by one or more decimal digits. Both integers shall contain the same number 3936 of digits. The characters preceding the integer shall be identical in the two symbolic names, and 3937 the integer formed by the digits in the second symbolic name shall be equal to or greater than the 3938 integer formed by the digits in the first name. This shall be interpreted as a series of symbolic 3939 names formed from the common part and each of the integers between the first and the second 3940 integer, inclusive. As an example, . . . is interpreted as the symbolic names 3941 , , , and , in that order. 3942 A character set mapping definition line shall exist for all symbolic names specified in Table 6-1 3943 (on page 133), and defines the coded character value that corresponds to the character glyph 138 Technical Standard (2000) (Draft July 28, 2000) Character Set Character Set Description File 3944 indicated in the table, or the coded character value that corresponds to the control character 3945 symbolic name. If the control characters commonly associated with the symbolic names in Table 3946 6-2 (on page 137) are supported by the implementation, the symbolic name and the 3947 corresponding encoding value shall be included in the file. Additional unique symbolic names 3948 may be included. A coded character value can be represented by more than one symbolic name. 3949 The encoding part is expressed as one (for single-byte character values) or more concatenated 3950 decimal, octal, or hexadecimal constants in the following formats: 3951 "%cd%u", , | 3952 "%cx%x", , 3953 "%c%o", , 3954 Decimal constants are represented by two or three decimal digits, preceded by the escape 3955 character and the lowercase letter 'd'; for example, "\d05", "\d97", or "\d143". 3956 Hexadecimal constants are represented by two hexadecimal digits, preceded by the escape 3957 character and the lowercase letter 'x'; for example, "\x05", "\x61", or "\x8f". Octal 3958 constants are represented by two or three octal digits, preceded by the escape character; for 3959 example, "\05", "\141", or "\217". In a portable charmap file, each constant represents an 8- 3960 bit byte. Implementations supporting other byte sizes may allow constants to represent values 3961 larger than those that can be represented in 8-bit bytes, and to allow additional digits in 3962 constants. When constants are concatenated for multi-byte character values, they shall be of the 3963 same type, and interpreted in byte order from first to last with the least significant byte of the 3964 multi-byte character specified by the last constant. The manner in which these constants are 3965 represented in the character stored in the system is implementation-defined. (This notation was | 3966 chosen for reasons of portability. There is no requirement that the internal representation in the 3967 computer memory be in this same order.) Omitting bytes from a multi-byte character definition 3968 produces undefined results. 3969 In lines defining ranges of symbolic names, the encoded value is the value for the first symbolic 3970 name in the range (the symbolic name preceding the ellipsis). Subsequent symbolic names 3971 defined by the range shall have encoding values in increasing order. For example, the line: 3972 ... \d129\d254 3973 is interpreted as: 3974 \d129\d254 3975 \d129\d255 3976 \d130\d0 3977 \d130\d1 3978 Note that this line is interpreted as the example even on systems with bytes larger than 8 bits. 3979 In lines defining ranges of symbolic names that also use the ISO/IEC 10646-1: 1993 standard 3980 position constant values, the conversion to the target codeset encoding value shall be performed 3981 before assignment of encoding values to symbolic names. 3982 The comment is optional. 3983 The following declarations can follow the character set mapping definitions (after the "END 3984 CHARMAP" statement). Each shall consist of the keyword shown in the following list, starting in 3985 column 1, followed by the value(s) to be associated to the keyword, as defined below. 3986 WIDTH An unsigned positive integer value defining the column width (see Section 3.106 3987 (on page 59)) for the printable characters in the coded character set specified in 3988 Table 6-1 (on page 133) and Table 6-2 (on page 137). | Base Definitions, Issue 6 139 Character Set Description File Character Set 3989 Notes to Reviewers | 3990 This section with side shading will not appear in the final copy. - Ed. | 3991 D3, XBD, ERN 90 suggests alternative wording for the text above: "the printable | 3992 characters specified between the CHARMAP and END CHARMAP statements". | 3993 The current wording is as per P1003.2b. When .2b is approved, an interpretation | 3994 should be filed. | 3995 Coded character set character values shall be defined using symbolic character | 3996 names followed by column width values. Defining a character with more than one 3997 WIDTH produces undefined results. The END WIDTH keyword shall be used to 3998 terminate the WIDTH definitions. Specifying the width of a non-printable 3999 character in a WIDTH declaration produces undefined results. 4000 WIDTH_DEFAULT 4001 An unsigned positive integer value defining the default column width for any 4002 printable character not listed by one of the WIDTH keywords. If no 4003 WIDTH_DEFAULT keyword is included in the charmap, the default character 4004 width shall be 1. 4005 Example 4006 After the "END CHARMAP" statement, a syntax for a width definition would be: 4007 WIDTH 4008 1 4009 1 4010 ... 1 4011 ... 2 4012 END WIDTH 4013 In this example, the numerical code point values represented by the symbols and are | 4014 assigned a width of 1. The code point values to inclusive (, , , and so on) 4015 are also assigned a width of 1. Using . . . would have required fewer lines, but the 4016 alternative was shown to demonstrate flexibility. The keyword WIDTH_DEFAULT could have 4017 been added as appropriate. 4018 6.4.1 State-Dependent Character Encodings 4019 This section addresses the use of state-dependent character encodings (that is, those in which the 4020 encoding of a character is dependent on one or more shift codes that may precede it). 4021 A single-shift encoding (where each character not in the initial shift state is preceded by a shift 4022 code) can be defined in the charmap format if each shift-code/character sequence is considered a 4023 multi-byte character, defined using the concatenated-constant format described in Section 6.4 4024 (on page 137). If the implementation supports a character encoding of this type, all of the 4025 standard utilities shall support it. A locking-shift encoding (where the state of the character is 4026 determined by a shift code that may affect more than the single character following it) could be 4027 defined with an extension to the charmap format described in Section 6.4 (on page 137). If the 4028 implementation supports a character encoding of this type, any of the standard utilities that 4029 describe character (versus byte) or text-file manipulation shall have the following characteristics: 4030 1. The utility shall process the statefully encoded data as a concatenation of state- 4031 independent characters. The presence of redundant locking shifts shall not affect the 4032 comparison of two statefully encoded strings. 140 Technical Standard (2000) (Draft July 28, 2000) Character Set Character Set Description File 4033 2. A utility that divides, truncates, or extracts substrings from statefully encoded data shall 4034 produce output that contains locking shifts at the beginning or end of the resulting data, if 4035 appropriate, to retain correct state information. Base Definitions, Issue 6 141 Character Set | 4036 | 142 Technical Standard (2000) (Draft July 28, 2000) Chapter 7 Locale 4037 4038 7.1 General 4039 A locale is the definition of the subset of a user's environment that depends on language and 4040 cultural conventions. It is made up from one or more categories. Each category is identified by 4041 its name and controls specific aspects of the behavior of components of the system. Category 4042 names correspond to the following environment variable names: 4043 LC_CTYPE Character classification and case conversion. 4044 LC_COLLATE Collation order. 4045 LC_TIME Date and time formats. 4046 LC_NUMERIC Numeric, non-monetary formatting. 4047 LC_MONETARY Monetary formatting. 4048 LC_MESSAGES Formats of informative and diagnostic messages and interactive responses. 4049 The standard utilities in the Shell and Utilities volume of IEEE Std. 1003.1-200x shall base their | 4050 behavior on the current locale, as defined in the ENVIRONMENT VARIABLES section for each | 4051 utility. The behavior of some of the C-language functions defined in the System Interfaces 4052 volume of IEEE Std. 1003.1-200x shall also be modified based on the current locale, as defined by 4053 the last call to setlocale( ). 4054 Locales other than those supplied by the implementation can be created via the localedef utility, | 4055 provided that the _POSIX2_LOCALEDEF symbol is defined on the system. Even if localedef is not | 4056 provided, all implementations conforming to the System Interfaces volume of | 4057 IEEE Std. 1003.1-200x shall provide one or more locales that behave as described in this chapter. | 4058 The input to the utility is described in Section 7.3 (on page 145). The value that is used to specify | 4059 a locale when using environment variables shall be the string specified as the name operand to 4060 the localedef utility when the locale was created. The strings "C" and "POSIX" are reserved as 4061 identifiers for the POSIX locale (see Section 7.2 (on page 144)). When the value of a locale 4062 environment variable begins with a slash ('/'), it is interpreted as the path name of the locale 4063 definition; the type of file (regular, directory, and so on) used to store the locale definition is | 4064 implementation-defined. If the value does not begin with a slash, the mechanism used to locate | 4065 the locale is implementation-defined. | 4066 If different character sets are used by the locale categories, the results achieved by an application 4067 utilizing these categories are undefined. Likewise, if different codesets are used for the data 4068 being processed by interfaces whose behavior is dependent on the current locale, or the codeset 4069 is different from the codeset assumed when the locale was created, the result is also undefined. 4070 Applications can select the desired locale by invoking the setlocale( ) function (or equivalent) 4071 with the appropriate value. If the function is invoked with an empty string, such as: 4072 setlocale(LC_ALL, ""); 4073 the value of the corresponding environment variable is used. If the environment variable is 4074 unset or is set to the empty string, the implementation shall set the appropriate environment as 4075 defined in Chapter 8 (on page 187). | Base Definitions, Issue 6 143 POSIX Locale Locale 4076 7.2 POSIX Locale 4077 Conforming systems shall provide a POSIX locale, also known as the C locale. The behavior of 4078 standard utilities and functions in the POSIX locale shall be as if the locale was defined via the 4079 localedef utility with input data from the POSIX locale tables in Section 7.3 (on page 145). 4080 The tables in Section 7.3 (on page 145) describe the characteristics and behavior of the POSIX 4081 locale for data consisting entirely of characters from the portable character set and the control 4082 character set. For other characters, the behavior is unspecified. For C-language programs, the 4083 POSIX locale is the default locale when the setlocale( ) function is not called. 4084 The POSIX locale can be specified by assigning to the appropriate environment variables the 4085 values "C" or "POSIX". 4086 All implementations shall define a locale as the default locale, to be invoked when no 4087 environment variables are set, or set to the empty string. This default locale can be the POSIX 4088 locale or any other implementation-defined locale. Some implementations may provide facilities | 4089 for local installation administrators to set the default locale, customizing it for each location. 4090 IEEE Std. 1003.1-200x does not require such a facility. | 144 Technical Standard (2000) (Draft July 28, 2000) Locale Locale Definition 4091 7.3 Locale Definition 4092 The capability to specify additional locales to those provided by an implementation is optional, 4093 denoted by the _POSIX2_LOCALEDEF symbol. If the option is not supported, only 4094 implementation-supplied locales are available. 4095 Locales can be described with the file format presented in this section. The file format is that 4096 accepted by the localedef utility. For the purposes of this section, the file is referred to as the locale 4097 definition file, but no locales shall be affected by this file unless it is processed by localedef or some 4098 similar mechanism. Any requirements in this section imposed upon the utility shall apply to 4099 localedef or to any other similar utility used to install locale information using the locale 4100 definition file format described here. 4101 The locale definition file shall contain one or more locale category source definitions, and shall 4102 not contain more than one definition for the same locale category. If the file contains source 4103 definitions for more than one category, implementation-defined categories, if present, shall | 4104 appear after the categories defined by Section 7.1 (on page 143). A category source definition 4105 contains either the definition of a category or a copy directive. For a description of the copy 4106 directive, see localedef. In the event that some of the information for a locale category, as 4107 specified in this volume of IEEE Std. 1003.1-200x, is missing from the locale source definition, the 4108 behavior of that category, if it is referenced, is unspecified. 4109 A category source definition consists of a category header, a category body, and a category 4110 trailer. A category header consists of the character string naming of the category, beginning with 4111 the characters LC_. The category trailer consists of the string "END", followed by one or more 4112 characters and the string used in the corresponding category header. 4113 The category body consists of one or more lines of text. Each line contains an identifier, 4114 optionally followed by one or more operands. Identifiers are either keywords, identifying a 4115 particular locale element, or collating elements. In addition to the keywords defined in this | 4116 volume of IEEE Std. 1003.1-200x, the source can contain implementation-defined keywords. | 4117 Each keyword within a locale has a unique name (that is, two categories cannot have a | 4118 commonly-named keyword); no keyword can start with the characters LC_. Identifiers are 4119 separated from the operands by one or more characters. 4120 Operands shall be characters, collating elements, or strings of characters. Strings are enclosed in 4121 double-quotes. Literal double-quotes within strings are preceded by the , 4122 described below. When a keyword is followed by more than one operand, the operands are 4123 separated by semicolons; characters are allowed both before and after a semicolon. 4124 The first category header in the file can be preceded by a line modifying the comment character. 4125 It shall have the following format, starting in column 1: 4126 "comment_char %c\n", 4127 The comment character defaults to the number sign ('#'). Blank lines and lines containing the 4128 in the first position are ignored. 4129 The first category header in the file can be preceded by a line modifying the escape character to 4130 be used in the file. It shall have the following format, starting in column 1: 4131 "escape_char %c\n", 4132 The escape character defaults to backslash, which is the character used in all examples shown in 4133 this volume of IEEE Std. 1003.1-200x. 4134 A line can be continued by placing an escape character as the last character on the line; this 4135 continuation character is discarded from the input. Although the implementation need not 4136 accept any one portion of a continued line with a length exceeding {LINE_MAX} bytes, it shall Base Definitions, Issue 6 145 Locale Definition Locale 4137 place no limits on the accumulated length of the continued line. Comment lines cannot be 4138 continued on a subsequent line using an escaped newline character. 4139 Individual characters, characters in strings, and collating elements shall be represented using 4140 symbolic names, as defined below. In addition, characters can be represented using the 4141 characters themselves or as octal, hexadecimal, or decimal constants. When non-symbolic 4142 notation is used, the resultant locale definitions are in many cases not portable between systems. 4143 The left angle bracket ('<') is a reserved symbol, denoting the start of a symbolic name; when 4144 used to represent itself it shall be preceded by the escape character. The following rules apply to 4145 character representation: 4146 1. A character can be represented via a symbolic name, enclosed within angle brackets '<' 4147 and '>'. The symbolic name, including the angle brackets, shall exactly match a symbolic 4148 name defined in the charmap file specified via the localedef -f option, and it shall be 4149 replaced by a character value determined from the value associated with the symbolic 4150 name in the charmap file. The use of a symbolic name not found in the charmap file shall 4151 constitute an error, unless the category is LC_CTYPE or LC_COLLATE, in which case it 4152 shall constitute a warning condition (see localedef for a description of action resulting from 4153 errors and warnings). The specification of a symbolic name in a collating-element or 4154 collating-symbol section that duplicates a symbolic name in the charmap file (if present) 4155 shall be an error. Use of the escape character or a right angle bracket within a symbolic 4156 name is invalid unless the character is preceded by the escape character. 4157 For example: 4158 ; "" 4159 2. A character in the portable character set can be represented by the character itself, in which 4160 case the value of the character is implementation-defined. (Implementations may allow | 4161 other characters to be represented as themselves, but such locale definitions are not | 4162 portable.) Within a string, the double-quote character, the escape character, and the right 4163 angle bracket character shall be escaped (preceded by the escape character) to be 4164 interpreted as the character itself. Outside strings, the characters: 4165 , ; < > escape_char 4166 shall be escaped to be interpreted as the character itself. 4167 For example: 4168 c "May" 4169 3. A character can be represented as an octal constant. An octal constant is specified as the | 4170 escape character followed by two or three octal digits. Each constant represents a byte | 4171 value. Multi-byte values can be represented by concatenated constants specified in byte 4172 order with the last constant specifying the least significant byte of the character. 4173 For example: 4174 \143;\347;\143\150 "\115\141\171" 4175 4. A character can be represented as a hexadecimal constant. A hexadecimal constant shall be 4176 specified as the escape character followed by an 'x' followed by two hexadecimal digits. | 4177 Each constant shall represent a byte value. Multi-byte values can be represented by | 4178 concatenated constants specified in byte order with the last constant specifying the least | 4179 significant byte of the character. | 4180 For example: 146 Technical Standard (2000) (Draft July 28, 2000) Locale Locale Definition 4181 \x63;\xe7;\x63\x68 "\x4d\x61\x79" 4182 5. A character can be represented as a decimal constant. A decimal constant shall be specified 4183 as the escape character followed by a 'd' followed by two or three decimal digits. Each | 4184 constant represents a byte value. Multi-byte values can be represented by concatenated | 4185 constants specified in byte order with the last constant specifying the least significant byte 4186 of the character. 4187 For example: 4188 \d99;\d231;\d99\d104 "\d77\d97\d121" 4189 Implementations supporting other byte sizes may allow constants to represent values larger | 4190 than those that can be represented in 8-bit bytes, and to allow additional digits in constants. | 4191 Implementations may accept single-digit octal, decimal, or hexadecimal constants following the | 4192 escape character. Only characters existing in the character set for which the locale definition is 4193 created can be specified, whether using symbolic names, the characters themselves, or octal, 4194 decimal, or hexadecimal constants. If a charmap file is present, only characters defined in the 4195 charmap can be specified using octal, decimal, or hexadecimal constants. Symbolic names not 4196 present in the charmap file can be specified and shall be ignored, as specified under item 1 4197 above. | 4198 7.3.1 LC_CTYPE 4199 The LC_CTYPE category shall define character classification, case conversion, and other 4200 character attributes. In addition, a series of characters can be represented by three adjacent 4201 periods representing an ellipsis symbol ("..."). The ellipsis specification shall be interpreted as 4202 meaning that all values between the values preceding and following it represent valid 4203 characters. The ellipsis specification is valid only within a single encoded character set; that is, 4204 within a group of characters of the same size. An ellipsis shall be interpreted as including in the 4205 list all characters with an encoded value higher than the encoded value of the character 4206 preceding the ellipsis and lower than the encoded value of the character following the ellipsis. 4207 For example: 4208 \x30;...;\x39; 4209 includes in the character class all characters with encoded values between the endpoints. 4210 The following keywords shall be recognized. In the descriptions, the term ``automatically 4211 included'' means that it shall not be an error either to include or omit any of the referenced 4212 characters; the implementation provides them if missing (even if the entire keyword is missing) 4213 and accepts them silently if present. When the implementation automatically includes a missing 4214 character, it shall have an encoded value dependent on the charmap file in effect (see the 4215 description of the localedef -f option); otherwise, it has a value derived from an implementation- | 4216 defined character mapping. | 4217 The character classes digit, xdigit, lower, upper, and space have a set of automatically included 4218 characters. These only need to be specified if the character values (that is, encoding) differ from 4219 the implementation default values. It is not possible to define a locale without these 4220 automatically included characters unless some implementation extension is used to prevent 4221 their inclusion. Such a definition would not be a proper superset of the C or POSIX locale and 4222 thus, it might not be possible for conforming applications to work properly. 4223 copy Specify the name of an existing locale to be used as the definition of this 4224 category. If this keyword is specified, no other keyword can be specified. Base Definitions, Issue 6 147 Locale Definition Locale 4225 upper Define characters to be classified as uppercase letters. 4226 In the POSIX locale, the 26 uppercase letters are included: 4227 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 4228 In a locale definition file, no character specified for the keywords cntrl, digit, 4229 punct, or space can be specified. The uppercase letters to , as defined | 4230 in Section 6.4 (on page 137) (the portable character set), are automatically | 4231 included in this class. 4232 lower Define characters to be classified as lowercase letters. 4233 In the POSIX locale, the 26 lowercase letters are included: 4234 a b c d e f g h i j k l m n o p q r s t u v w x y z 4235 In a locale definition file, no character specified for the keywords cntrl, digit, 4236 punct, or space can be specified. The lowercase letters to of the | 4237 portable character set are automatically included in this class. | 4238 alpha Define characters to be classified as letters. 4239 In the POSIX locale, all characters in the classes upper and lower are included. 4240 In a locale definition file, no character specified for the keywords cntrl, digit, 4241 punct, or space can be specified. Characters classified as either upper or lower 4242 are automatically included in this class. 4243 digit Define the characters to be classified as numeric digits. 4244 In the POSIX locale, only: 4245 0 1 2 3 4 5 6 7 8 9 4246 are included. 4247 In a locale definition file, only the digits , , , , | 4248 , , , , , and can be specified, and in | 4249 contiguous ascending sequence by numerical value. The digits to | 4250 of the portable character set are automatically included in this class. | 4251 The definition of character class digit requires that only ten characters-the 4252 ones defining digits-can be specified; alternative digits (for example, Hindi 4253 or Kanji) cannot be specified here. However, the encoding may vary if an 4254 implementation supports more than one encoding. 4255 alnum Define characters to be classified as letters and numeric digits. Only the 4256 characters specified for the alpha and digit keywords shall be specified. 4257 Characters specified for the keywords alpha and digit are automatically 4258 included in this class. 4259 space Define characters to be classified as white-space characters. 4260 In the POSIX locale, at a minimum, the characters , , | 4261 , , , and are included. | 4262 In a locale definition file, no character specified for the keywords upper, 4263 lower, alpha, digit, graph, or xdigit can be specified. The characters , 4264 , , , , and of the 4265 portable character set, and any characters included in the class blank are 4266 automatically included in this class. 148 Technical Standard (2000) (Draft July 28, 2000) Locale Locale Definition 4267 cntrl Define characters to be classified as control characters. 4268 In the POSIX locale, no characters in classes alpha or print are included. 4269 In a locale definition file, no character specified for the keywords upper, 4270 lower, alpha, digit, punct, graph, print, or xdigit can be specified. 4271 punct Define characters to be classified as punctuation characters. 4272 In the POSIX locale, neither the character nor any characters in 4273 classes alpha, digit, or cntrl are included. 4274 In a locale definition file, no character specified for the keywords upper, 4275 lower, alpha, digit, cntrl, xdigit, or as the character can be specified. 4276 graph Define characters to be classified as printable characters, not including the 4277 character. 4278 In the POSIX locale, all characters in classes alpha, digit, and punct are 4279 included; no characters in class cntrl are included. 4280 In a locale definition file, characters specified for the keywords upper, lower, 4281 alpha, digit, xdigit, and punct are automatically included in this class. No 4282 character specified for the keyword cntrl can be specified. 4283 print Define characters to be classified as printable characters, including the 4284 character. 4285 In the POSIX locale, all characters in class graph are included; no characters in 4286 class cntrl are included. 4287 In a locale definition file, characters specified for the keywords upper, lower, 4288 alpha, digit, xdigit, punct, graph, and the character are automatically | 4289 included in this class. No character specified for the keyword cntrl can be 4290 specified. 4291 xdigit Define the characters to be classified as hexadecimal digits. 4292 In the POSIX locale, only: 4293 0 1 2 3 4 5 6 7 8 9 A B C D E F a b c d e f 4294 are included. 4295 In a locale definition file, only the characters defined for the class digit can be 4296 specified, in contiguous ascending sequence by numerical value, followed by 4297 one or more sets of six characters representing the hexadecimal digits 10 to 15 4298 inclusive, with each set in ascending order (for example, , , , , | 4299 , , , , , , , ). The digits to , the | 4300 uppercase letters to , and the lowercase letters to of the | 4301 portable character set are automatically included in this class. | 4302 The definition of character class xdigit requires that the characters included in 4303 character class digit be included here also. 4304 blank Define characters to be classified as characters. 4305 In the POSIX locale, only the and characters are included. 4306 In a locale definition file, the characters and are automatically 4307 included in this class. Base Definitions, Issue 6 149 Locale Definition Locale 4308 charclass Define one or more locale-specific character class names as strings separated 4309 by semicolons. Each named character class can then be defined subsequently 4310 in the LC_CTYPE definition. A character class name consists of at least one 4311 and at most {CHARCLASS_NAME_MAX} bytes of alphanumeric characters 4312 from the portable file name character set. The first character of a character 4313 class name cannot be a digit. The name cannot match any of the LC_CTYPE 4314 keywords defined in this volume of IEEE Std. 1003.1-200x. Future revisions of 4315 IEEE Std. 1003.1-200x will not specify any LC_CTYPE keywords containing 4316 uppercase letters. 4317 charclass-name Define characters to be classified as belonging to the named locale-specific 4318 character class. In the POSIX locale, the locale-specific named character classes 4319 need not exist. 4320 If a class name is defined by a charclass keyword, but no characters are 4321 subsequently assigned to it, this is not an error; it represents a class without 4322 any characters belonging to it. 4323 The charclass-name can be used as the property argument to the wctype( ) 4324 function, in regular expression and shell pattern-matching bracket 4325 expressions, and by the tr command. 4326 toupper Define the mapping of lowercase letters to uppercase letters. 4327 In the POSIX locale, at a minimum, the 26 lowercase characters: 4328 a b c d e f g h i j k l m n o p q r s t u v w x y z 4329 are mapped to the corresponding 26 uppercase characters: 4330 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 4331 In a locale definition file, the operand consists of character pairs, separated by 4332 semicolons. The characters in each character pair are separated by a comma 4333 and the pair enclosed by parentheses. The first character in each pair is the 4334 lowercase letter, the second the corresponding uppercase letter. Only 4335 characters specified for the keywords lower and upper can be specified. The | 4336 lowercase letters to , and their corresponding uppercase letters to | 4337 , of the portable character set are automatically included in this mapping, | 4338 but only when the toupper keyword is omitted from the locale definition. | 4339 tolower Define the mapping of uppercase letters to lowercase letters. 4340 In the POSIX locale, at a minimum, the 26 uppercase characters: 4341 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 4342 are mapped to the corresponding 26 lowercase characters: 4343 a b c d e f g h i j k l m n o p q r s t u v w x y z 4344 In a locale definition file, the operand consists of character pairs, separated by 4345 semicolons. The characters in each character pair are separated by a comma 4346 and the pair enclosed by parentheses. The first character in each pair is the 4347 uppercase letter, the second the corresponding lowercase letter. Only 4348 characters specified for the keywords lower and upper can be specified. If the 4349 tolower keyword is omitted from the locale definition, the mapping is the 4350 reverse mapping of the one specified for toupper. 150 Technical Standard (2000) (Draft July 28, 2000) Locale Locale Definition 4351 The following table shows the character class combinations allowed: 4352 Table 7-1 Valid Character Class Combinations _____________________________________________________________________________ 4353 _ Can Also Belong To __________________________________________________________________ 4354 _In Class upper lower alpha digit space cntrl punct graph print xdigit blank ____________________________________________________________________________ 4355 upper - A x x x x A A - x 4356 lower - A x x x x A A - x 4357 alpha - - x x x x A A - x 4358 digit x x x x x x A A A x 4359 space x x x x - * * * x - 4360 cntrl x x x x - x x x x - 4361 punct x x x x - x A A x - 4362 graph - - - - - x - A - - 4363 print - - - - - x - - - - 4364 xdigit - - - - x x x A A x 4365 _ blank x x x x A - * * * x ____________________________________________________________________________ 4366 Notes: 4367 1. Explanation of codes: 4368 A Automatically included; see text. 4369 - Permitted. 4370 x Mutually-exclusive. 4371 * See note 2. 4372 2. The character, which is part of the space and blank classes, cannot 4373 belong to punct or graph, but automatically belongs to the print class. Other 4374 space or blank characters can be classified as any of punct, graph, or print. 4375 The character classifications for the POSIX locale follow; the code listing depicting the localedef 4376 input, the table representing the same information, sorted by character. 4377 LC_CTYPE 4378 # The following is the POSIX locale LC_CTYPE. 4379 # "alpha" is by default "upper" and "lower" 4380 # "alnum" is by definition "alpha" and "digit" 4381 # "print" is by default "alnum", "punct" and the character 4382 # "graph" is by default "alnum" and "punct" 4383 # 4384 upper ;;;;;;;;;;;;;\ 4385 ;;

;;;;;;;;;; 4386 # 4387 lower ;;;;;;;;;;;;;\ 4388 ;;

;;;;;;;;;; 4389 # 4390 digit ;;;;;;;\ 4391 ;; 4392 # 4393 space ;;;;\ 4394 ; 4395 # 4396 cntrl ;;;;;\ Base Definitions, Issue 6 151 Locale Definition Locale 4397 ;;\ 4398 ;;;;;;;;\ 4399 ;;;;;;;;\ 4400 ;;;;;;;;\ 4401 ; 4402 # 4403 punct ;;;\ 4404 ;;;;\ 4405 ;;;\ 4406 ;;;;;\ 4407 ;;;;\ 4408 ;;;\ 4409 ;;;\ 4410 ;;;;\ 4411 ;; 4412 # 4413 xdigit ;;;;;;;;\ 4414 ;;;;;;;;;;;;; 4415 # 4416 blank ; 4417 # 4418 toupper (,);(,);(,);(,);(,);\ 4419 (,);(,);(,);(,);(,);\ 4420 (,);(,);(,);(,);(,);\ 4421 (

,

);(,);(,);(,);(,);\ 4422 (,);(,);(,);(,);(,);(,) 4423 # 4424 tolower (,);(,);(,);(,);(,);\ 4425 (,);(,);(,);(,);(,);\ 4426 (,);(,);(,);(,);(,);\ 4427 (

,

);(,);(,);(,);(,);\ 4428 (,);(,);(,);(,);(,);(,) 4429 END LC_CTYPE 152 Technical Standard (2000) (Draft July 28, 2000) Locale Locale Definition 4430 ____________________________________________________________________ 4431 _ Symbolic Name Other Case Character Classes ___________________________________________________________________ 4432 cntrl 4433 cntrl 4434 cntrl 4435 cntrl 4436 cntrl 4437 cntrl 4438 cntrl 4439 cntrl 4440 cntrl 4441 cntrl, space, blank 4442 cntrl, space 4443 cntrl, space 4444 cntrl, space 4445 cntrl, space 4446 cntrl 4447 cntrl 4448 cntrl 4449 cntrl 4450 cntrl 4451 cntrl 4452 cntrl 4453 cntrl 4454 cntrl 4455 cntrl 4456 cntrl 4457 cntrl 4458 cntrl 4459 cntrl 4460 cntrl 4461 cntrl 4462 cntrl 4463 cntrl 4464 space, print, blank 4465 punct, print, graph 4466 punct, print, graph 4467 punct, print, graph 4468 punct, print, graph 4469 punct, print, graph 4470 punct, print, graph 4471 punct, print, graph 4472 punct, print, graph 4473 punct, print, graph 4474 punct, print, graph 4475 punct, print, graph 4476 punct, print, graph 4477 punct, print, graph 4478 _ punct, print, graph ___________________________________________________________________ Base Definitions, Issue 6 153 Locale Definition Locale 4479 ____________________________________________________________________ 4480 _ Symbolic Name Other Case Character Classes ___________________________________________________________________ 4481 punct, print, graph 4482 digit, xdigit, print, graph 4483 digit, xdigit, print, graph 4484 digit, xdigit, print, graph 4485 digit, xdigit, print, graph 4486 digit, xdigit, print, graph 4487 digit, xdigit, print, graph 4488 digit, xdigit, print, graph 4489 digit, xdigit, print, graph 4490 digit, xdigit, print, graph 4491 digit, xdigit, print, graph 4492 punct, print, graph 4493 punct, print, graph 4494 punct, print, graph 4495 punct, print, graph 4496 punct, print, graph 4497 punct, print, graph 4498 punct, print, graph 4499 upper, xdigit, alpha, print, graph 4500 upper, xdigit, alpha, print, graph 4501 upper, xdigit, alpha, print, graph 4502 upper, xdigit, alpha, print, graph 4503 upper, xdigit, alpha, print, graph 4504 upper, xdigit, alpha, print, graph 4505 upper, alpha, print, graph 4506 upper, alpha, print, graph 4507 upper, alpha, print, graph 4508 upper, alpha, print, graph 4509 upper, alpha, print, graph 4510 upper, alpha, print, graph 4511 upper, alpha, print, graph 4512 upper, alpha, print, graph 4513 upper, alpha, print, graph 4514

upper, alpha, print, graph 4515 upper, alpha, print, graph 4516 upper, alpha, print, graph 4517 upper, alpha, print, graph 4518 upper, alpha, print, graph 4519 upper, alpha, print, graph 4520 upper, alpha, print, graph 4521 upper, alpha, print, graph 4522 upper, alpha, print, graph 4523 upper, alpha, print, graph 4524 upper, alpha, print, graph 4525 punct, print, graph 4526 punct, print, graph 4527 _ punct, print, graph ___________________________________________________________________ 154 Technical Standard (2000) (Draft July 28, 2000) Locale Locale Definition 4528 ____________________________________________________________________ 4529 _ Symbolic Name Other Case Character Classes ___________________________________________________________________ 4530 punct, print, graph 4531 punct, print, graph 4532 punct, print, graph 4533 lower, xdigit, alpha, print, graph 4534 lower, xdigit, alpha, print, graph 4535 lower, xdigit, alpha, print, graph 4536 lower, xdigit, alpha, print, graph 4537 lower, xdigit, alpha, print, graph 4538 lower, xdigit, alpha, print, graph 4539 lower, alpha, print, graph 4540 lower, alpha, print, graph 4541 lower, alpha, print, graph 4542 lower, alpha, print, graph 4543 lower, alpha, print, graph 4544 lower, alpha, print, graph 4545 lower, alpha, print, graph 4546 lower, alpha, print, graph 4547 lower, alpha, print, graph 4548

lower, alpha, print, graph 4549 lower, alpha, print, graph 4550 lower, alpha, print, graph 4551 lower, alpha, print, graph 4552 lower, alpha, print, graph 4553 lower, alpha, print, graph 4554 lower, alpha, print, graph 4555 lower, alpha, print, graph 4556 lower, alpha, print, graph 4557 lower, alpha, print, graph 4558 lower, alpha, print, graph 4559 punct, print, graph 4560 punct, print, graph 4561 punct, print, graph 4562 punct, print, graph 4563 _ cntrl ___________________________________________________________________ 4564 7.3.2 LC_COLLATE 4565 The LC_COLLATE category provides a collation sequence definition for numerous utilities in the | 4566 Shell and Utilities volume of IEEE Std. 1003.1-200x (sort, uniq, and so on), regular expression | 4567 matching (see Chapter 9 (on page 195)) and the strcoll( ), strxfrm( ), wcscoll( ), and wcsxfrm( ) 4568 functions in the System Interfaces volume of IEEE Std. 1003.1-200x. 4569 A collation sequence definition shall define the relative order between collating elements 4570 (characters and multi-character collating elements) in the locale. This order is expressed in terms 4571 of collation values; that is, by assigning each element one or more collation values (also known 4572 as collation weights). This does not imply that implementations shall assign such values, but 4573 that ordering of strings using the resultant collation definition in the locale behaves as if such 4574 assignment is done and used in the collation process. At least the following capabilities are 4575 provided: 4576 1. Multi-character collating elements. Specification of multi-character collating elements 4577 (that is, sequences of two or more characters to be collated as an entity). Base Definitions, Issue 6 155 Locale Definition Locale 4578 2. User-defined ordering of collating elements. Each collating element shall be assigned a 4579 collation value defining its order in the character (or basic) collation sequence. This 4580 ordering is used by regular expressions and pattern matching and, unless collation weights 4581 are explicitly specified, also as the collation weight to be used in sorting. 4582 3. Multiple weights and equivalence classes. Collating elements can be assigned one or 4583 more (up to the limit {COLL_WEIGHTS_MAX}, as defined in ) collating weights 4584 for use in sorting. The first weight is hereafter referred to as the primary weight. 4585 4. One-to-many mapping. A single character is mapped into a string of collating elements. 4586 5. Equivalence class definition. Two or more collating elements have the same collation 4587 value (primary weight). 4588 6. Ordering by weights. When two strings are compared to determine their relative order, 4589 the two strings are first broken up into a series of collating elements; the elements in each 4590 successive pair of elements are then compared according to the relative primary weights 4591 for the elements. If equal, and more than one weight has been assigned, then the pairs of 4592 collating elements are recompared according to the relative subsequent weights, until 4593 either a pair of collating elements compare unequal or the weights are exhausted. 4594 The following keywords shall be recognized in a collation sequence definition. They are 4595 described in detail in the following sections. 4596 copy Specify the name of an existing locale to be used as the definition of this 4597 category. If this keyword is specified, no other keyword can be specified. 4598 collating-element Define a collating-element symbol representing a multi-character 4599 collating element. This keyword is optional. 4600 collating-symbol Define a collating symbol for use in collation order statements. This 4601 keyword is optional. 4602 order_start Define collation rules. This statement is followed by one or more collation 4603 order statements, assigning character collation values and collation 4604 weights to collating elements. 4605 order_end Specify the end of the collation-order statements. 4606 7.3.2.1 The collating-element Keyword 4607 In addition to the collating elements in the character set, the collating-element keyword can be 4608 used to define multi-character collating elements. The syntax is as follows: 4609 "collating-element %s from \"%s\"\n", , 4610 The operand shall be a symbolic name, enclosed between angle brackets ('<' 4611 and '>'), and shall not duplicate any symbolic name in the current charmap file (if any), or any 4612 other symbolic name defined in this collation definition. The string operand is a string of two or 4613 more characters that collates as an entity. A defined via this keyword is only 4614 recognized with the LC_COLLATE category. 4615 For example: 4616 collating-element from "" 4617 collating-element from "" 4618 collating-element from "ll" 156 Technical Standard (2000) (Draft July 28, 2000) Locale Locale Definition 4619 7.3.2.2 The collating-symbol Keyword 4620 This keyword can be used to define symbols for use in collation sequence statements; that is, 4621 between the order_start and the order_end keywords. The syntax is as follows: 4622 "collating-symbol %s\n", 4623 The shall be a symbolic name, enclosed between angle brackets ('<' and 4624 '>'), and shall not duplicate any symbolic name in the current charmap file (if any), or any 4625 other symbolic name defined in this collation definition. A defined via this 4626 keyword is only recognized with the LC_COLLATE category. 4627 For example: 4628 collating-symbol 4629 collating-symbol 4630 The collating-symbol keyword defines a symbolic name that can be associated with a relative 4631 position in the character order sequence. While such a symbolic name does not represent any 4632 collating element, it can be used as a weight. 4633 7.3.2.3 The order_start Keyword 4634 The order_start keyword shall precede collation order entries and also define the number of 4635 weights for this collation sequence definition and other collation rules. 4636 The syntax of the order_start keyword is as follows: 4637 "order_start %s;%s;...;%s\n", , ... 4638 The operands to the order_start keyword are optional. If present, the operands define rules to be 4639 applied when strings are compared. The number of operands define how many weights each 4640 element is assigned; if no operands are present, one forward operand is assumed. If present, the 4641 first operand defines rules to be applied when comparing strings using the first (primary) 4642 weight; the second when comparing strings using the second weight, and so on. Operands shall 4643 be separated by semicolons (';'). Each operand shall consist of one or more collation 4644 directives, separated by commas (','). If the number of operands exceeds the 4645 {COLL_WEIGHTS_MAX} limit, the utility shall issue a warning message. The following 4646 directives shall be supported: 4647 forward Specifies that comparison operations for the weight level shall proceed from start 4648 of string towards the end of string. 4649 backward Specifies that comparison operations for the weight level shall proceed from end of 4650 string towards the beginning of string. 4651 position Specifies that comparison operations for the weight level shall consider the relative 4652 position of elements in the strings not subject to IGNORE. The string containing 4653 an element not subject to IGNORE after the fewest collating elements subject to 4654 IGNORE from the start of the compare collates first. If both strings contain a 4655 character not subject to IGNORE in the same relative position, the collating values 4656 assigned to the elements shall determine the ordering. In case of equality, 4657 subsequent characters not subject to IGNORE are considered in the same manner. 4658 The directives forward and backward are mutually-exclusive. 4659 For example: 4660 order_start forward;backward Base Definitions, Issue 6 157 Locale Definition Locale 4661 If no operands are specified, a single forward operand shall be assumed. 4662 The character (and collating element) order is defined by the order in which characters and 4663 elements are specified between the order_start and order_end keywords. This character order is 4664 used in range expressions in regular expressions (see Chapter 9). Weights assigned to the 4665 characters and elements define the collation sequence; in the absence of weights, the character 4666 order is also the collation sequence. 4667 The position keyword provides the capability to consider, in a compare, the relative position of 4668 characters not subject to IGNORE. As an example, consider the two strings "o-ring" and 4669 "or-ing". Assuming the hyphen is subject to IGNORE on the first pass, the two strings 4670 compare equal, and the position of the hyphen is immaterial. On second pass, all characters 4671 except the hyphen are subject to IGNORE, and in the normal case the two strings would again 4672 compare equal. By taking position into account, the first collates before the second. 4673 7.3.2.4 Collation Order 4674 The order_start keyword shall be followed by collating identifier entries. The syntax for the 4675 collating element entries is as follows: 4676 "%s %s;%s;...;%s\n", , , , ... 4677 Each collating-identifier shall consist of either a character (in any of the forms defined in Section 4678 7.3 (on page 145)), a , a , an ellipsis, or the special symbol 4679 UNDEFINED. The order in which collating elements are specified determines the character 4680 order sequence, such that each collating element shall compare less than the elements following 4681 it. 4682 A shall be used to specify multi-character collating elements, and indicates 4683 that the character sequence specified via the is to be collated as a unit and in 4684 the relative order specified by its place. 4685 A can be used to define a position in the relative order for use in weights. No 4686 weights can be specified with a . 4687 The ellipsis symbol specifies that a sequence of characters collates according to their encoded 4688 character values. It shall be interpreted as indicating that all characters with a coded character 4689 set value higher than the value of the character in the preceding line, and lower than the coded 4690 character set value for the character in the following line, in the current coded character set, shall 4691 be placed in the character collation order between the previous and the following character in 4692 ascending order according to their coded character set values. An initial ellipsis shall be 4693 interpreted as if the preceding line specified the NUL character, and a trailing ellipsis as if the 4694 following line specified the highest coded character set value in the current coded character set. 4695 An ellipsis shall be treated as invalid if the preceding or following lines do not specify characters 4696 in the current coded character set. The use of the ellipsis symbol ties the definition to a specific 4697 coded character set and may preclude the definition from being portable between 4698 implementations. 4699 The symbol UNDEFINED shall be interpreted as including all coded character set values not 4700 specified explicitly or via the ellipsis symbol. Such characters shall be inserted in the character 4701 collation order at the point indicated by the symbol, and in ascending order according to their 4702 coded character set values. If no UNDEFINED symbol is specified, and the current coded 4703 character set contains characters not specified in this section, the utility shall issue a warning 4704 message and place such characters at the end of the character collation order. 4705 The optional operands for each collation-element shall be used to define the primary, secondary, 4706 or subsequent weights for the collating element. The first operand specifies the relative primary 158 Technical Standard (2000) (Draft July 28, 2000) Locale Locale Definition 4707 weight, the second the relative secondary weight, and so on. Two or more collation-elements can 4708 be assigned the same weight; they belong to the same equivalence class if they have the same 4709 primary weight. Collation shall behave as if, for each weight level, elements subject to IGNORE 4710 are removed, unless the position collation directive is specified for the corresponding level with 4711 the order_start keyword. Then each successive pair of elements shall be compared according to 4712 the relative weights for the elements. If the two strings compare equal, the process is repeated 4713 for the next weight level, up to the limit {COLL_WEIGHTS_MAX}. 4714 Weights shall be expressed as characters (in any of the forms specified in Section 7.3 (on page 4715 145)), s, s, an ellipsis, or the special symbol IGNORE. A 4716 single character, a , or a shall represent the relative position 4717 in the character collating sequence of the character or symbol, rather than the character or 4718 characters themselves. Thus, rather than assigning absolute values to weights, a particular 4719 weight is expressed using the relative order value assigned to a collating element based on its 4720 order in the character collation sequence. 4721 One-to-many mapping is indicated by specifying two or more concatenated characters or 4722 symbolic names. For example, if the character is given the string "" as a weight, 4723 comparisons are performed as if all occurrences of the character are replaced by 4724 "" (assuming that "" has the collating weight ""). If it is necessary to define 4725 and "" as an equivalence class, then a collating element must be defined for the 4726 string "ss". 4727 All characters specified via an ellipsis shall by default be assigned unique weights, equal to the 4728 relative order of characters. Characters specified via an explicit or implicit UNDEFINED special 4729 symbol shall by default be assigned the same primary weight (that is, they belong to the same 4730 equivalence class). An ellipsis symbol as a weight shall be interpreted to mean that each 4731 character in the sequence has unique weights, equal to the relative order of their character in the 4732 character collation sequence. The use of the ellipsis as a weight shall be treated as an error if the 4733 collating element is neither an ellipsis nor the special symbol UNDEFINED. 4734 The special keyword IGNORE as a weight shall indicate that when strings are compared using 4735 the weights at the level where IGNORE is specified, the collating element shall be ignored; that 4736 is, as if the string did not contain the collating element. In regular expressions and pattern 4737 matching, all characters that are subject to IGNORE in their primary weight form an 4738 equivalence class. 4739 An empty operand shall be interpreted as the collating element itself. 4740 For example, the order statement: 4741 ; 4742 is equal to: 4743 4744 An ellipsis can be used as an operand if the collating element was an ellipsis, and shall be 4745 interpreted as the value of each character defined by the ellipsis. 4746 The collation order as defined in this section defines the interpretation of bracket expressions in 4747 regular expressions (see Section 9.3.5 (on page 199)). 4748 For example: Base Definitions, Issue 6 159 Locale Definition Locale 4749 order_start forward;backward 4750 UNDEFINED IGNORE;IGNORE 4751 4752 ; 4753 ... ;... 4754 ; 4755 ; 4756 ; 4757 ; 4758 ; 4759 ; 4760 ; 4761 ; 4762 ; 4763 "";"" 4764 order_end 4765 This example is interpreted as follows: 4766 1. The UNDEFINED means that all characters not specified in this definition (explicitly or 4767 via the ellipsis) shall be ignored for collation purposes; for regular expression purposes 4768 they are ordered first. 4769 2. All characters between and 'a' shall have the same primary equivalence class 4770 and individual secondary weights based on their ordinal encoded values. 4771 3. All characters based on the uppercase or lowercase character 'a' belong to the same 4772 primary equivalence class. 4773 4. The multi-character collating element is represented by the collating symbol 4774 and belongs to the same primary equivalence class as the multi-character collating element 4775 . 4776 7.3.2.5 The order_end Keyword 4777 The collating order entries shall be terminated with an order_end keyword. 4778 The collation sequence definition of the POSIX locale follows; the code listing depicts the 4779 localedef input. 4780 LC_COLLATE 4781 # This is the POSIX locale definition for the LC_COLLATE category. 4782 # The order is the same as in the ASCII codeset. 4783 order_start forward 4784 4785 4786 4787 4788 4789 4790 4791 4792 4793 4794 4795 160 Technical Standard (2000) (Draft July 28, 2000) Locale Locale Definition 4796 4797 4798 4799 4800 4801 4802 4803 4804 4805 4806 4807 4808 4809 4810 4811 4812 4813 4814 4815 4816 4817 4818 4819 4820 4821 4822 4823 4824 4825 4826 4827 4828 4829 4830 4831 4832 4833 4834 4835 4836 4837 4838 4839 4840 4841 4842 4843 4844 4845 4846 4847 Base Definitions, Issue 6 161 Locale Definition Locale 4848 4849 4850 4851 4852 4853 4854 4855 4856 4857 4858 4859 4860 4861 4862 4863 4864

4865 4866 4867 4868 4869 4870 4871 4872 4873 4874 4875 4876 4877 4878 4879 4880 4881 4882 4883 4884 4885 4886 4887 4888 4889 4890 4891 4892 4893 4894 4895 4896

4897 4898 4899 162 Technical Standard (2000) (Draft July 28, 2000) Locale Locale Definition 4900 4901 4902 4903 4904 4905 4906 4907 4908 4909 4910 4911 4912 order_end 4913 # 4914 END LC_COLLATE 4915 7.3.3 LC_MONETARY 4916 The LC_MONETARY category shall define the rules and symbols that are used to format 4917 XSI monetary numeric information. This information is available through the localeconv( ) function 4918 and is used by the strfmon( ) function. 4919 XSI Some of the information is also available in an alternative form via the nl_langinfo ( ) function 4920 (see CRNCYSTR in ). 4921 The following items are defined in this category of the locale. The item names are the keywords 4922 recognized by the localedef utility when defining a locale. They are also similar to the member 4923 names of the lconv structure defined in ; see for the exact symbols in the 4924 header. The localeconv( ) function returns {CHAR_MAX} for unspecified integer items and the 4925 empty string (" ") for unspecified or size zero string items. 4926 In a locale definition file, the operands are strings, formatted as indicated by the grammar in 4927 Section 7.4 (on page 176). For some keywords, the strings can contain only integers. Keywords 4928 that are not provided, string values set to the empty string (" "), or integer keywords set to -1, 4929 are used to indicate that the value is not available in the locale. 4930 copy Specify the name of an existing locale to be used as the definition of this 4931 category. If this keyword is specified, no other keyword can be specified. 4932 Note: This is a localedef utility keyword, unavailable through 4933 localeconv( ). 4934 int_curr_symbol The international currency symbol. The operand is a four-character string, 4935 with the first three characters containing the alphabetic international 4936 currency symbol in accordance with those specified in the ISO 4217: 1995 4937 standard. The fourth character is the character used to separate the 4938 international currency symbol from the monetary quantity. 4939 currency_symbol The string that shall be used as the local currency symbol. 4940 mon_decimal_point The operand is a string containing the symbol that shall be used as the 4941 decimal delimiter (radix character) in monetary formatted quantities. In 4942 contexts where standards (such as the ISO C standard) limit the 4943 mon_decimal_point to a single byte, the result of specifying a multi-byte 4944 operand is unspecified. Base Definitions, Issue 6 163 Locale Definition Locale 4945 mon_thousands_sep The operand is a string containing the symbol that shall be used as a 4946 separator for groups of digits to the left of the decimal delimiter in 4947 formatted monetary quantities. In contexts where standards limit the 4948 mon_thousands_sep to a single byte, the result of specifying a multi-byte 4949 operand is unspecified. 4950 mon_grouping Define the size of each group of digits in formatted monetary quantities. 4951 The operand is a sequence of integers separated by semicolons. Each 4952 integer specifies the number of digits in each group, with the initial 4953 integer defining the size of the group immediately preceding the decimal 4954 delimiter, and the following integers defining the preceding groups. If the 4955 last integer is not -1, then the size of the previous group (if any) shall be 4956 repeatedly used for the remainder of the digits. If the last integer is -1, 4957 then no further grouping shall be performed. 4958 The following is an example of the interpretation of the mon_grouping 4959 keyword. Assuming that the value to be formatted is 123456789 and the 4960 mon_thousands_sep is ''', then the following table shows the result. 4961 The third column shows the equivalent string in the ISO C standard that 4962 would be used by the localeconv( ) function to accommodate this 4963 grouping._________________________________________________ 4964 _mon_grouping Formatted Value ISO C String ________________________________________________ 4965 3;-1 123456'789 "\3\177" 4966 3 123'456'789 "\3" 4967 3;2;-1 1234'56'789 "\3\2\177" 4968 3;2 12'34'56'789 "\3\2" 4969 _ -1 123456789 "\177" ________________________________________________ 4970 In these examples, the octal value of {CHAR_MAX} is 177. 4971 positive_sign A string that shall be used to indicate a non-negative-valued formatted 4972 monetary quantity. 4973 negative_sign A string that shall be used to indicate a negative-valued formatted 4974 monetary quantity. 4975 int_frac_digits An integer representing the number of fractional digits (those to the right 4976 of the decimal delimiter) to be written in a formatted monetary quantity 4977 using int_curr_symbol. 4978 frac_digits An integer representing the number of fractional digits (those to the right 4979 of the decimal delimiter) to be written in a formatted monetary quantity 4980 using currency_symbol. 4981 p_cs_precedes An integer set to 1 if the currency_symbol or int_curr_symbol precedes 4982 the value for a monetary quantity with a non-negative value, and set to 0 4983 if the symbol succeeds the value. 4984 p_sep_by_space An integer set to 0 if no space separates the currency_symbol or 4985 int_curr_symbol from the value for a monetary quantity with a non- 4986 negative value, set to 1 if a space separates the symbol from the value, 4987 and set to 2 if a space separates the symbol and the sign string, if adjacent. 4988 n_cs_precedes An integer set to 1 if the currency_symbol or int_curr_symbol precedes 4989 the value for a monetary quantity with a negative value, and set to 0 if the 4990 symbol succeeds the value. 164 Technical Standard (2000) (Draft July 28, 2000) Locale Locale Definition 4991 n_sep_by_space An integer set to 0 if no space separates the currency_symbol or 4992 int_curr_symbol from the value for a monetary quantity with a negative 4993 value, set to 1 if a space separates the symbol from the value, and set to 2 4994 if a space separates the symbol and the sign string, if adjacent. 4995 p_sign_posn An integer set to a value indicating the positioning of the positive_sign 4996 for a monetary quantity with a non-negative value. The following integer 4997 values shall be recognized for both p_sign_posn and n_sign_posn: 4998 0 Parentheses enclose the quantity and the currency_symbol or 4999 int_curr_symbol. 5000 1 The sign string precedes the quantity and the currency_symbol or 5001 int_curr_symbol. 5002 2 The sign string succeeds the quantity and the currency_symbol or 5003 int_curr_symbol. 5004 3 The sign string precedes the currency_symbol or int_curr_symbol. 5005 4 The sign string succeeds the currency_symbol or int_curr_symbol. 5006 n_sign_posn An integer set to a value indicating the positioning of the negative_sign 5007 for a negative formatted monetary quantity. 5008 The following table shows the result of various combinations: _________________________________________________________________________ 5009 p_sep_by_space 5010 _ 2 1 0 ________________________________________________________________________ 5011 p_cs_precedes = 1 p_sign_posn = 0 ($1.25) ($ 1.25) ($1.25) 5012 p_sign_posn = 1 + $1.25 +$ 1.25 +$1.25 5013 p_sign_posn = 2 $1.25 + $ 1.25+ $1.25+ 5014 p_sign_posn = 3 + $1.25 +$ 1.25 +$1.25 5015 p_sign_posn = 4 $ +1.25 $+ 1.25 $+1.25 5016 p_cs_precedes = 0 p_sign_posn = 0 (1.25 $) (1.25 $) (1.25$) 5017 p_sign_posn = 1 +1.25 $ +1.25 $ +1.25$ 5018 p_sign_posn = 2 1.25$ + 1.25 $+ 1.25$+ 5019 p_sign_posn = 3 1.25+ $ 1.25 +$ 1.25+$ 5020 _ p_sign_posn = 4 1.25$ + 1.25 $+ 1.25$+ ________________________________________________________________________ 5021 The monetary formatting definitions for the POSIX locale follow; the code listing depicting the 5022 XSI localedef input, the table representing the same information with the addition of localeconv( ) and 5023 nl_langinfo ( )formats. All values are unspecified in the POSIX locale. 5024 LC_MONETARY 5025 # This is the POSIX locale definition for 5026 # the LC_MONETARY category. 5027 # 5028 int_curr_symbol "" 5029 currency_symbol "" 5030 mon_decimal_point "" 5031 mon_thousands_sep "" 5032 mon_grouping -1 5033 positive_sign "" 5034 negative_sign "" 5035 int_frac_digits -1 5036 frac_digits -1 Base Definitions, Issue 6 165 Locale Definition Locale 5037 p_cs_precedes -1 5038 p_sep_by_space -1 5039 n_cs_precedes -1 5040 n_sep_by_space -1 5041 p_sign_posn -1 5042 n_sign_posn -1 5043 # 5044 END LC_MONETARY ____________________________________________________________________________ 5045 POSIX locale langinfo localeconv( ) localedef 5046 _ Item Value Constant Value Value ___________________________________________________________________________ 5047 currency_symbol N/A CRNCYSTR " " " " 5048 frac_digits N/A - CHAR_MAX -1 5049 int_curr_symbol N/A - " " " " 5050 int_frac_digits N/A - CHAR_MAX -1 5051 mon_decimal_point N/A - " " " " 5052 mon_thousands_sep N/A - " " " " 5053 mon_grouping N/A - " " " " 5054 positive_sign N/A - " " " " 5055 negative_sign N/A - " " " " 5056 p_cs_precedes N/A CRNCYSTR CHAR_MAX -1 5057 n_cs_precedes N/A CRNCYSTR CHAR_MAX -1 5058 p_sep_by_space N/A - CHAR_MAX -1 5059 n_sep_by_space N/A - CHAR_MAX -1 5060 p_sign_posn N/A - CHAR_MAX -1 5061 _ n_sign_posn N/A - CHAR_MAX -1 ___________________________________________________________________________ 5062 XSI In the preceding table, the langinfo Constant column represents an XSI-conformant extension. 5063 The entry N/A indicates that the value is not available in the POSIX locale. | 5064 7.3.4 LC_NUMERIC 5065 The LC_NUMERIC category shall define the rules and symbols that are used to format non- 5066 XSI monetary numeric information. This information is available through the localeconv( ) function. 5067 Some of the information is also available in an alternative form via the nl_langinfo ( ) function. 5068 The following items are defined in this category of the locale. The item names are the keywords 5069 recognized by the localedef utility when defining a locale. They are also similar to the member 5070 names of the lconv structure defined in ; see for the exact symbols in the 5071 header. The localeconv( ) function returns {CHAR_MAX} for unspecified integer items and the 5072 empty string (" ") for unspecified or size zero string items. 5073 In a locale definition file, the operands are strings, formatted as indicated by the grammar in 5074 Section 7.4 (on page 176). For some keywords, the strings can only contain integers. Keywords 5075 that are not provided, string values set to the empty string (" "), or integer keywords set to -1, 5076 shall be used to indicate that the value is not available in the locale. The following keywords 5077 shall be recognized: 5078 copy Specify the name of an existing locale to be used as the definition of this 5079 category. If this keyword is specified, no other keyword can be specified. 5080 Note: This is a localedef utility keyword, unavailable through localeconv( ). 5081 decimal_point The operand is a string containing the symbol that shall be used as the 5082 decimal delimiter (radix character) in numeric, non-monetary formatted 5083 quantities. This keyword cannot be omitted and cannot be set to the empty 166 Technical Standard (2000) (Draft July 28, 2000) Locale Locale Definition 5084 string. In contexts where standards limit the decimal_point to a single byte, 5085 the result of specifying a multi-byte operand shall be unspecified. 5086 thousands_sep The operand is a string containing the symbol that shall be used as a separator 5087 for groups of digits to the left of the decimal delimiter in numeric, non- 5088 monetary formatted monetary quantities. In contexts where standards limit 5089 the thousands_sep to a single byte, the result of specifying a multi-byte 5090 operand shall be unspecified. 5091 grouping Define the size of each group of digits in formatted non-monetary quantities. 5092 The operand is a sequence of integers separated by semicolons. Each integer 5093 specifies the number of digits in each group, with the initial integer defining 5094 the size of the group immediately preceding the decimal delimiter, and the 5095 following integers defining the preceding groups. If the last integer is not -1, 5096 then the size of the previous group (if any) shall be repeatedly used for the 5097 remainder of the digits. If the last integer is -1, then no further grouping shall 5098 be performed. 5099 The non-monetary numeric formatting definitions for the POSIX locale follow; the code listing 5100 depicting the localedef input, the table representing the same information with the addition of 5101 XSI localeconv( ) values, and nl_langinfo ( )constants. 5102 LC_NUMERIC 5103 # This is the POSIX locale definition for 5104 # the LC_NUMERIC category. 5105 # 5106 decimal_point "" 5107 thousands_sep "" 5108 grouping -1 5109 # 5110 END LC_NUMERIC ________________________________________________________________________ 5111 POSIX Locale langinfo localeconv( ) localedef 5112 _ Item Value Constant Value Value _______________________________________________________________________ 5113 decimal_point "." RADIXCHAR "." . 5114 thousands_sep N/A THOUSEP " " " " 5115 _ grouping N/A - " " -1 _______________________________________________________________________ 5116 Notes to Reviewers 5117 This section with side shading will not appear in the final copy. - Ed. 5118 D1, XBD, ERN 112 asked why the grouping in the POSIX locale is -1, but the grouping line in the 5119 POSIX Locale Value column of this table is N/A. The response from Gary Miller (via Mark 5120 Brown) was that they are saying the same thing; the -1 means that there is no grouping, therefore 5121 the grouping is not applicable. 5122 XSI In the preceding table, the langinfo Constant column represents an XSI-conforming extension. 5123 The entry N/A indicates that the value is not available in the POSIX locale. | Base Definitions, Issue 6 167 Locale Definition Locale 5124 7.3.5 LC_TIME 5125 The LC_TIME category shall define the interpretation of the field descriptors supported by the 5126 XSI date utility and affects the behavior of the strftime( ), wcsftime( ), strptime( ), and nl_langinfo ( ) 5127 functions. Because the interfaces for C-language access and locale definition differ significantly, 5128 they are described separately. 5129 7.3.5.1 LC_TIME Locale Definition 5130 For locale definition, the following mandatory keywords shall be recognized: 5131 copy Specify the name of an existing locale to be used as the definition of this 5132 category. If this keyword is specified, no other keyword can be specified. 5133 abday Define the abbreviated weekday names, corresponding to the %a field 5134 descriptor (conversion specification in the strftime( ), wcsftime( ), and strptime( ) 5135 functions). The operand consists of seven semicolon-separated strings, each 5136 surrounded by double-quotes. The first string shall be the abbreviated name of 5137 the day corresponding to Sunday, the second the abbreviated name of the day 5138 corresponding to Monday, and so on. 5139 day Define the full weekday names, corresponding to the %A field descriptor. The 5140 operand consists of seven semicolon-separated strings, each surrounded by 5141 double-quotes. The first string is the full name of the day corresponding to 5142 Sunday, the second the full name of the day corresponding to Monday, and so 5143 on. 5144 abmon Define the abbreviated month names, corresponding to the %b field 5145 descriptor. The operand consists of twelve semicolon-separated strings, each 5146 surrounded by double-quotes. The first string shall be the abbreviated name of 5147 the first month of the year (January), the second the abbreviated name of the 5148 second month, and so on. 5149 mon Define the full month names, corresponding to the %B field descriptor. The 5150 operand consists of twelve semicolon-separated strings, each surrounded by 5151 double-quotes. The first string shall be the full name of the first month of the 5152 year (January), the second the full name of the second month, and so on. 5153 d_t_fmt Define the appropriate date and time representation, corresponding to the %c 5154 field descriptor. The operand consists of a string, and can contain any 5155 combination of characters and field descriptors. In addition, the string can 5156 contain escape sequences defined in the table in Table 5-1 (on page 130) ('\\', 5157 '\a', '\b', '\f', '\n', '\r', '\t', '\v'). 5158 d_fmt Define the appropriate date representation, corresponding to the %x field 5159 descriptor. The operand consists of a string, and can contain any combination 5160 of characters and field descriptors. In addition, the string can contain escape 5161 sequences defined in the table in Table 5-1 (on page 130). 5162 t_fmt Define the appropriate time representation, corresponding to the %X field 5163 descriptor. The operand consists of a string, and can contain any combination 5164 of characters and field descriptors. In addition, the string can contain escape 5165 sequences defined in the table in Table 5-1 (on page 130). 5166 am_pm Define the appropriate representation of the ante meridiem and post meridiem 5167 strings, corresponding to the %p field descriptor. The operand consists of two 5168 strings, separated by a semicolon, each surrounded by double-quotes. The 5169 first string shall represent the ante meridiem designation, the last string the post 168 Technical Standard (2000) (Draft July 28, 2000) Locale Locale Definition 5170 meridiem designation. 5171 t_fmt_ampm Define the appropriate time representation in the 12-hour clock format with 5172 am_pm, corresponding to the %r field descriptor. The operand consists of a 5173 string and can contain any combination of characters and field descriptors. If 5174 the string is empty, the 12-hour format is not supported in the locale. 5175 era Define how years are counted and displayed for each era in a locale. The 5176 operand consists of semicolon-separated strings. Each string is an era 5177 description segment with the format: 5178 direction:offset:start_date:end_date:era_name:era_format 5179 according to the definitions below. There can be as many era description 5180 segments as are necessary to describe the different eras. 5181 Note: The start of an era might not be the earliest point in the era-it may 5182 be the latest. For example, the Christian era BC starts on the day 5183 before January 1, AD 1, and increases with earlier time. 5184 direction Either a '+' or a '-' character. The '+' character indicates that 5185 years closer to the start_date have lower numbers than those 5186 closer to the end_date. The '-' character indicates that years 5187 closer to the start_date have higher numbers than those closer to 5188 the end_date. 5189 offset The number of the year closest to the start_date in the era, 5190 corresponding to the %Ey field descriptor. 5191 start_date A date in the form yyyy/mm/dd, where yyyy, mm, and dd are the 5192 year, month, and day numbers respectively of the start of the 5193 era. Years prior to AD 1 are represented as negative numbers. 5194 end_date The ending date of the era, in the same format as the start_date, 5195 or one of the two special values "-*" or "+*". The value "-*" 5196 indicates that the ending date is the beginning of time. The value 5197 "+*" indicates that the ending date is the end of time. 5198 era_name A string representing the name of the era, corresponding to the 5199 %EC field descriptor. 5200 era_format A string for formatting the year in the era, corresponding to the 5201 %EY field descriptor. 5202 era_d_fmt Define the format of the date in alternative era notation, corresponding to the 5203 %Ex field descriptor. 5204 era_t_fmt Define the locale's appropriate alternative time format, corresponding to the 5205 %EX field descriptor. 5206 era_d_t_fmt Define the locale's appropriate alternative date and time format, 5207 corresponding to the %Ec field descriptor. 5208 alt_digits Define alternative symbols for digits, corresponding to the %O field descriptor 5209 modifier. The operand consists of semicolon-separated strings, each 5210 surrounded by double-quotes. The first string is the alternative symbol 5211 corresponding with zero, the second string the symbol corresponding with 5212 one, and so on. Up to 100 alternative symbol strings can be specified. The %O 5213 modifier indicates that the string corresponding to the value specified via the 5214 field descriptor is used instead of the value. Base Definitions, Issue 6 169 Locale Definition Locale 5215 7.3.5.2 LC_TIME C-Language Access 5216 XSI The following information can be accessed. These correspond to constants defined in 5217 and used as arguments to the nl_langinfo ( ) function. 5218 ABDAY_x The abbreviated weekday names (for example Sun), where x is a number from 5219 1 to 7. 5220 DAY_x The full weekday names (for example Sunday), where x is a number from 1 to 5221 7. 5222 ABMON_x The abbreviated month names (for example Jan), where x is a number from 1 5223 to 12. 5224 MON_x The full month names (for example January), where x is a number from 1 to 5225 12. 5226 D_T_FMT The appropriate date and time representation. 5227 D_FMT The appropriate date representation. 5228 T_FMT The appropriate time representation. 5229 AM_STR The appropriate ante-meridiem affix. 5230 PM_STR The appropriate post-meridiem affix. 5231 T_FMT_AMPM The appropriate time representation in the 12-hour clock format with 5232 AM_STR and PM_STR. 5233 ERA The era description segments, which describe how years are counted and 5234 displayed for each era in a locale. Each era description segment has the format: 5235 direction:offset:start_date:end_date:era_name:era_format 5236 according to the definitions below. There are as many era description 5237 segments as are necessary to describe the different eras. Era description 5238 segments are separated by semicolons. | 5239 direction Either a '+' or a '-' character. The '+' character indicates that 5240 years closer to the start_date have lower numbers than those 5241 closer to the end_date. The '-' character indicates that years 5242 closer to the start_date have higher numbers than those closer to 5243 the end_date. 5244 offset The number of the year closest to the start_date in the era. 5245 start_date A date in the form yyyy/mm/dd, where yyyy, mm, and dd are the 5246 year, month, and day numbers respectively of the start of the 5247 era. Years prior to AD 1 are represented as negative numbers. 5248 end_date The ending date of the era, in the same format as the start_date, 5249 or one of the two special values "-*" or "+*". The value "-*" 5250 indicates that the ending date is the beginning of time. The value 5251 "+*" indicates that the ending date is the end of time. 5252 era_name The era, corresponding to the %EC conversion specification. 5253 era_format The format of the year in the era, corresponding to the %EY 5254 conversion specification. 5255 ERA_D_FMT The era date format. 170 Technical Standard (2000) (Draft July 28, 2000) Locale Locale Definition 5256 ERA_T_FMT The locale's appropriate alternative time format, corresponding to the %EX 5257 field descriptor. 5258 ERA_D_T_FMT The locale's appropriate alternative date and time format, corresponding to 5259 the %Ec field descriptor. 5260 ALT_DIGITS The alternative symbols for digits, corresponding to the %O conversion 5261 specification modifier. The value consists of semicolon-separated symbols. 5262 The first is the alternative symbol corresponding to zero, the second is the 5263 symbol corresponding to one, and so on. Up to 100 alternative symbols may 5264 be specified. 5265 The following table displays the correspondence between the items described above and the 5266 conversion specifiers used by the date utility and the strftime( ), wcsftime( ), and strptime( ) 5267 functions. 5268 _____________________________________________________________ 5269 _localedef Keyword langinfo Constant Conversion Specifier ____________________________________________________________ 5270 abday ABDAY_x %a 5271 day DAY_x %A 5272 abmon ABMON_x %b 5273 mon MON %B 5274 d_t_fmt D_T_FMT %c 5275 d_fmt D_FMT %x 5276 t_fmt T_FMT %X 5277 am_pm AM_STR %p 5278 am_pm PM_STR %p 5279 t_fmt_ampm T_FMT_AMPM %r 5280 era ERA %EC, %Ey, %EY 5281 era_d_fmt ERA_D_FMT %Ex 5282 era_t_fmt ERA_T_FMT %EX 5283 era_d_t_fmt ERA_D_T_FMT %Ec 5284 _ alt_digits ALT_DIGITS %O ____________________________________________________________ 5285 In the preceding table, the langinfo Constant column represents an XSI-conformant extension. | 5286 7.3.5.3 LC_TIME General Information 5287 The following is an example for Japan that supports the current plus last three Emperors and 5288 reverts to Western style numbering for years prior to the Meiji era. The example also allows for 5289 the custom of using a special name for the first year of an era instead of using 1. (The examples 5290 substitute romaji where kanji should be used.) 5291 era_d_fmt "%EY%mgatsu%dnichi (%a)" 5292 era "+:2:1990/01/01:+*:Heisei:%EC%Eynen";\ 5293 "+:1:1989/01/08:1989/12/31:Heisei:%ECgannen";\ 5294 "+:2:1927/01/01:1989/01/07:Shouwa:%EC%Eynen";\ 5295 "+:1:1926/12/25:1926/12/31:Shouwa:%ECgannen";\ 5296 "+:2:1913/01/01:1926/12/24:Taishou:%EC%Eynen";\ 5297 "+:1:1912/07/30:1912/12/31:Taishou:%ECgannen";\ 5298 "+:2:1869/01/01:1912/07/29:Meiji:%EC%Eynen";\ 5299 "+:1:1868/09/08:1868/12/31:Meiji:%ECgannen";\ 5300 "-:1868:1868/09/07:-*::%Ey" Base Definitions, Issue 6 171 Locale Definition Locale 5301 Assuming that the current date is September 21, 1991, a request to date or strftime( ) would yield 5302 the following results: 5303 %Ec - Heisei3nen9gatsu21nichi (Sat) 14:39:26 5304 %EC - Heisei 5305 %Ex - Heisei3nen9gatsu21nichi (Sat) 5306 %Ey - 3 5307 %EY - Heisei3nen 5308 Example era definitions for the Republic of China: 5309 era "+:2:1913/01/01:+*:ChungHwaMingGuo:%EC%EyNen";\ 5310 "+:1:1912/1/1:1912/12/31:ChungHwaMingGuo:%ECYuenNen";\ 5311 "+:1:1911/12/31:-*:MingChien:%EC%EyNen" 5312 Example definitions for the Christian Era: 5313 era "+:0:0000/01/01:+*:AD:%EC %Ey";\ 5314 "+:1:-0001/12/31:-*:BC:%Ey %EC" 5315 The LC_TIME category definition of the POSIX locale follows; the code listing depicts the 5316 XSI localedef input; the table depicts the langinfo items defined in this category. 5317 LC_TIME 5318 # This is the POSIX locale definition for 5319 # the LC_TIME category. 5320 # 5321 # Abbreviated weekday names (%a) 5322 abday "";"";"";"";\ 5323 "";"";"" 5324 # 5325 # Full weekday names (%A) 5326 day "";"";\ 5327 "";"";\ 5328 "";"";\ 5329 "" 5330 # 5331 # Abbreviated month names (%b) 5332 abmon "";"";"";\ 5333 "

";"";"";\ 5334 "";"";"

";\ 5335 "";"";"" 5336 # 5337 # Full month names (%B) 5338 mon "";"";\ 5339 "";"

";\ 5340 "";"";\ 5341 "";"";\ 5342 "

";"";\ 5343 "";"" 5344 # 5345 # Equivalent of AM/PM (%p) "AM";"PM" 5346 am_pm "";"

" 5347 # 5348 # Appropriate date and time representation (%c) 5349 # "%a %b %e %H:%M:%S %Y" 172 Technical Standard (2000) (Draft July 28, 2000) Locale Locale Definition 5350 d_t_fmt "\ 5351 \ 5352 \ 5353 " 5354 # 5355 # Appropriate date representation (%x) "%m/%d/%y" 5356 d_fmt "\ 5357 " 5358 # 5359 # Appropriate time representation (%X) "%H:%M:%S" 5360 t_fmt "\ 5361 " 5362 # 5363 # Appropriate 12-hour time representation (%r) "%I:%M:%S %p" 5364 t_fmt_ampm "\ 5365

" 5366 # 5367 END LC_TIME Base Definitions, Issue 6 173 Locale Definition Locale 5368 _____________________________________________________________________________________ 5369 _ Item POSIX Locale Value Item POSIX Locale Value ____________________________________________________________________________________ 5370 XSI D_T_FMT "%a %b %e %H:%M:%S %Y" MON_3 "March" 5371 D_FMT "%m/%d/%y" MON_4 "April" 5372 T_FMT "%H:%M:%S" MON_5 "May" 5373 AM_STR "AM" MON_6 "June" 5374 PM_STR "PM" MON_7 "July" 5375 T_FMT_AMPM "%I:%M:%S %p" MON_8 "August" 5376 DAY_1 "Sunday" MON_9 "September" 5377 DAY_2 "Monday" MON_10 "October" 5378 DAY_3 "Tuesday" MON_11 "November" 5379 DAY_4 "Wednesday" MON_12 "December" 5380 DAY_5 "Thursday" ABMON_1 "Jan" 5381 DAY_6 "Friday" ABMON_2 "Feb" 5382 DAY_7 "Saturday" ABMON_3 "Mar" 5383 ABDAY_1 "Sun" ABMON_4 "Apr" 5384 ABDAY_2 "Mon" ABMON_5 "May" 5385 ABDAY_3 "Tue" ABMON_6 "Jun" 5386 ABDAY_4 "Wed" ABMON_7 "Jul" 5387 ABDAY_5 "Thu" ABMON_8 "Aug" 5388 ABDAY_6 "Fri" ABMON_9 "Sep" 5389 ABDAY_7 "Sat" ABMON_10 "Oct" 5390 MON_1 "January" ABMON_11 "Nov" 5391 _ MON_2 "February" ABMON_12 "Dec" ____________________________________________________________________________________ 5392 7.3.6 LC_MESSAGES 5393 The LC_MESSAGES category shall define the format and values for affirmative and negative 5394 responses. 5395 XSI The message catalog used by the standard utilities and selected by the catopen( ) function shall be 5396 determined by the setting of NLSPATH; see Chapter 8 (on page 187). The LC_MESSAGES 5397 category can be specified as part of an NLSPATH substitution field. 5398 XSI The following keywords shall be recognized as part of the locale definition file. The 5399 nl_langinfo ( ) function accepts uppercase versions of the first four keywords. 5400 copy Specify the name of an existing locale to be used as the definition of this category. 5401 If this keyword is specified, no other keyword can be specified. 5402 yesexpr The operand consists of an extended regular expression (see Section 9.4 (on page 5403 203)) that describes the acceptable affirmative response to a question expecting an 5404 affirmative or negative response. 5405 noexpr The operand consists of an extended regular expression that describes the 5406 acceptable negative response to a question expecting an affirmative or negative 5407 response. 5408 The format and values for affirmative and negative responses of the POSIX locale follow; the 5409 code listing depicting the localedef input, the table representing the same information with the 5410 XSI addition ofnl_langinfo ( ) constants. 5411 LC_MESSAGES 5412 # This is the POSIX locale definition for 5413 # the LC_MESSAGES category. 5414 # 174 Technical Standard (2000) (Draft July 28, 2000) Locale Locale Definition 5415 yesexpr "" 5416 # 5417 noexpr "" 5418 # 5419 XSI yesstr "yes" 5420 nostr "no" 5421 END LC_MESSAGES ____________________________________________________________ 5422 _localedef Keyword langinfo Constant POSIX Locale Value ___________________________________________________________ 5423 yesexpr YESEXPR " [yY]" 5424 noexpr NOEXPR " [nN]" 5425 XSI yesstr YESSTR "yes" (LEGACY) 5426 XSI _ nostr NOSTR "no" (LEGACY) ___________________________________________________________ 5427 7.3.6.1 LC_MESSAGES Application Usage 5428 XSI The yesstr and nostr locale keywords and the YESSTR and NOSTR langinfo items were formerly 5429 used to match user affirmative and negative responses. In IEEE Std. 1003.1-200x, the yesexpr, 5430 noexpr, YESEXPR, and NOEXPR extended regular expressions have replaced them. However, 5431 they have been retained for backward compatibility to allow an application to include a sample 5432 desired response in a prompting message. They are marked LEGACY. Applications should use 5433 the general locale-based messaging facilities to issue such prompting messages. Base Definitions, Issue 6 175 Locale Definition Grammar Locale 5434 7.4 Locale Definition Grammar 5435 The grammar and lexical conventions in this section shall together describe the syntax for the 5436 locale definition source. The general conventions for this style of grammar are described in the | 5437 Shell and Utilities volume of IEEE Std. 1003.1-200x, Section 1.10, Grammar Conventions. The | 5438 grammar shall take precedence over the text in this chapter. 5439 7.4.1 Locale Lexical Conventions 5440 The lexical conventions for the locale definition grammar are described in this section. 5441 The following tokens shall be processed (in addition to those string constants shown in the 5442 grammar): 5443 LOC_NAME A string of characters representing the name of a locale. 5444 CHAR Any single character. 5445 NUMBER A decimal number, represented by one or more decimal digits. 5446 COLLSYMBOL A symbolic name, enclosed between angle brackets. The string 5447 cannot duplicate any charmap symbol defined in the current 5448 charmap (if any), or a COLLELEMENT symbol. 5449 COLLELEMENT A symbolic name, enclosed between angle brackets, which cannot 5450 duplicate either any charmap symbol or a COLLSYMBOL symbol. | 5451 CHARCLASS A string of alphanumeric characters from the portable character set, | 5452 the first of which is not a digit, consisting of at least one and at most 5453 {CHARCLASS_NAME_MAX} bytes, and optionally surrounded by 5454 double-quotes. | 5455 CHARSYMBOL A symbolic name, enclosed between angle brackets, from the current 5456 charmap (if any). 5457 OCTAL_CHAR One or more octal representations of the encoding of each byte in a 5458 single character. The octal representation consists of an escape 5459 character (normally a backslash) followed by two or more octal 5460 digits. 5461 HEX_CHAR One or more hexadecimal representations of the encoding of each 5462 byte in a single character. The hexadecimal representation consists of 5463 an escape character followed by the constant x and two or more 5464 hexadecimal digits. 5465 DECIMAL_CHAR One or more decimal representations of the encoding of each byte in 5466 a single character. The decimal representation consists of an escape 5467 character followed by a character 'd' and two or more decimal 5468 digits. 5469 ELLIPSIS The string "...". 5470 EXTENDED_REG_EXP An extended regular expression as defined in the grammar in Section 5471 9.5 (on page 206). 5472 EOL The line termination character newline. 176 Technical Standard (2000) (Draft July 28, 2000) Locale Locale Definition Grammar 5473 7.4.2 Locale Grammar 5474 This section presents the grammar for the locale definition. 5475 %token LOC_NAME 5476 %token CHAR 5477 %token NUMBER 5478 %token COLLSYMBOL COLLELEMENT 5479 %token CHARSYMBOL OCTAL_CHAR HEX_CHAR DECIMAL_CHAR 5480 %token ELLIPSIS 5481 %token EXTENDED_REG_EXP 5482 %token EOL 5483 %start locale_definition 5484 %% 5485 locale_definition : global_statements locale_categories 5486 | locale_categories 5487 ; 5488 global_statements : global_statements symbol_redefine 5489 | symbol_redefine 5490 ; 5491 symbol_redefine : 'escape_char' CHAR EOL 5492 | 'comment_char' CHAR EOL 5493 ; 5494 locale_categories : locale_categories locale_category 5495 | locale_category 5496 ; 5497 locale_category : lc_ctype | lc_collate | lc_messages 5498 | lc_monetary | lc_numeric | lc_time 5499 ; 5500 /* The following grammar rules are common to all categories */ 5501 char_list : char_list char_symbol 5502 | char_symbol 5503 ; 5504 char_symbol : CHAR | CHARSYMBOL 5505 | OCTAL_CHAR | HEX_CHAR | DECIMAL_CHAR 5506 ; 5507 elem_list : elem_list char_symbol 5508 | elem_list COLLSYMBOL 5509 | elem_list COLLELEMENT 5510 | char_symbol 5511 | COLLSYMBOL 5512 | COLLELEMENT 5513 ; 5514 symb_list : symb_list COLLSYMBOL 5515 | COLLSYMBOL 5516 ; Base Definitions, Issue 6 177 Locale Definition Grammar Locale 5517 locale_name : LOC_NAME 5518 | '"' LOC_NAME '"' 5519 ; 5520 /* The following is the LC_CTYPE category grammar */ 5521 lc_ctype : ctype_hdr ctype_keywords ctype_tlr 5522 | ctype_hdr 'copy' locale_name EOL ctype_tlr 5523 ; 5524 ctype_hdr : 'LC_CTYPE' EOL 5525 ; 5526 ctype_keywords : ctype_keywords ctype_keyword 5527 | ctype_keyword 5528 ; 5529 ctype_keyword : charclass_keyword charclass_list EOL 5530 | charconv_keyword charconv_list EOL 5531 | 'charclass' charclass_namelist EOL 5532 ; 5533 charclass_namelist : charclass_namelist ';' CHARCLASS 5534 | CHARCLASS 5535 ; 5536 charclass_keyword : 'upper' | 'lower' | 'alpha' | 'digit' 5537 | 'punct' | 'xdigit' | 'space' | 'print' 5538 | 'graph' | 'blank' | 'cntrl' | 'alnum' 5539 | CHARCLASS 5540 ; 5541 charclass_list : charclass_list ';' char_symbol 5542 | charclass_list ';' ELLIPSIS ';' char_symbol 5543 | char_symbol 5544 ; 5545 charconv_keyword : 'toupper' 5546 | 'tolower' 5547 ; 5548 charconv_list : charconv_list ';' charconv_entry 5549 | charconv_entry 5550 ; 5551 charconv_entry : '(' char_symbol ',' char_symbol ')' 5552 ; 5553 ctype_tlr : 'END' 'LC_CTYPE' EOL 5554 ; 5555 /* The following is the LC_COLLATE category grammar */ 5556 lc_collate : collate_hdr collate_keywords collate_tlr 5557 | collate_hdr 'copy' locale_name EOL collate_tlr 5558 ; 5559 collate_hdr : 'LC_COLLATE' EOL 5560 ; 178 Technical Standard (2000) (Draft July 28, 2000) Locale Locale Definition Grammar 5561 collate_keywords : order_statements 5562 | opt_statements order_statements 5563 ; 5564 opt_statements : opt_statements collating_symbols 5565 | opt_statements collating_elements 5566 | collating_symbols 5567 | collating_elements 5568 ; 5569 collating_symbols : 'collating-symbol' COLLSYMBOL EOL 5570 ; 5571 collating_elements : 'collating-element' COLLELEMENT 5572 | 'from' '"' elem_list '"' EOL 5573 ; 5574 order_statements : order_start collation_order order_end 5575 ; 5576 order_start : 'order_start' EOL 5577 | 'order_start' order_opts EOL 5578 ; 5579 order_opts : order_opts ';' order_opt 5580 | order_opt 5581 ; 5582 order_opt : order_opt ',' opt_word 5583 | opt_word 5584 ; 5585 opt_word : 'forward' | 'backward' | 'position' 5586 ; 5587 collation_order : collation_order collation_entry 5588 | collation_entry 5589 ; 5590 collation_entry : COLLSYMBOL EOL 5591 | collation_element weight_list EOL 5592 | collation_element EOL 5593 ; 5594 collation_element : char_symbol 5595 | COLLELEMENT 5596 | ELLIPSIS 5597 | 'UNDEFINED' 5598 ; 5599 weight_list : weight_list ';' weight_symbol 5600 | weight_list ';' 5601 | weight_symbol 5602 ; 5603 weight_symbol : /* empty */ 5604 | char_symbol 5605 | COLLSYMBOL 5606 | '"' elem_list '"' Base Definitions, Issue 6 179 Locale Definition Grammar Locale 5607 | '"' symb_list '"' 5608 | ELLIPSIS 5609 | 'IGNORE' 5610 ; 5611 order_end : 'order_end' EOL 5612 ; 5613 collate_tlr : 'END' 'LC_COLLATE' EOL 5614 ; 5615 /* The following is the LC_MESSAGES category grammar */ 5616 lc_messages : messages_hdr messages_keywords messages_tlr 5617 | messages_hdr 'copy' locale_name EOL messages_tlr 5618 ; 5619 messages_hdr : 'LC_MESSAGES' EOL 5620 ; 5621 messages_keywords : messages_keywords messages_keyword 5622 | messages_keyword 5623 ; 5624 messages_keyword : 'yesexpr' '"' EXTENDED_REG_EXP '"' EOL 5625 | 'noexpr' '"' EXTENDED_REG_EXP '"' EOL 5626 | 'yesstr' '"' char_list '"' EOL 5627 | 'nostr' '"' char_list '"' EOL 5628 ; 5629 messages_tlr : 'END' 'LC_MESSAGES' EOL 5630 ; 5631 /* The following is the LC_MONETARY category grammar */ 5632 lc_monetary : monetary_hdr monetary_keywords monetary_tlr 5633 | monetary_hdr 'copy' locale_name EOL monetary_tlr 5634 ; 5635 monetary_hdr : 'LC_MONETARY' EOL 5636 ; 5637 monetary_keywords : monetary_keywords monetary_keyword 5638 | monetary_keyword 5639 ; 5640 monetary_keyword : mon_keyword_string mon_string EOL 5641 | mon_keyword_char NUMBER EOL 5642 | mon_keyword_char '-1' EOL 5643 | mon_keyword_grouping mon_group_list EOL 5644 ; 5645 mon_keyword_string : 'int_curr_symbol' | 'currency_symbol' 5646 | 'mon_decimal_point' | 'mon_thousands_sep' 5647 | 'positive_sign' | 'negative_sign' 5648 ; 5649 mon_string : '"' char_list '"' 5650 | '""' 5651 ; 180 Technical Standard (2000) (Draft July 28, 2000) Locale Locale Definition Grammar 5652 mon_keyword_char : 'int_frac_digits' | 'frac_digits' 5653 | 'p_cs_precedes' | 'p_sep_by_space' 5654 | 'n_cs_precedes' | 'n_sep_by_space' 5655 | 'p_sign_posn' | 'n_sign_posn' 5656 ; 5657 mon_keyword_grouping : 'mon_grouping' 5658 ; 5659 mon_group_list : NUMBER 5660 | mon_group_list ';' NUMBER 5661 ; 5662 monetary_tlr : 'END' 'LC_MONETARY' EOL 5663 ; 5664 /* The following is the LC_NUMERIC category grammar */ 5665 lc_numeric : numeric_hdr numeric_keywords numeric_tlr 5666 | numeric_hdr 'copy' locale_name EOL numeric_tlr 5667 ; 5668 numeric_hdr : 'LC_NUMERIC' EOL 5669 ; 5670 numeric_keywords : numeric_keywords numeric_keyword 5671 | numeric_keyword 5672 ; 5673 numeric_keyword : num_keyword_string num_string EOL 5674 | num_keyword_grouping num_group_list EOL 5675 ; 5676 num_keyword_string : 'decimal_point' 5677 | 'thousands_sep' 5678 ; 5679 num_string : '"' char_list '"' 5680 | '""' 5681 ; 5682 num_keyword_grouping: 'grouping' 5683 ; 5684 num_group_list : NUMBER 5685 | num_group_list ';' NUMBER 5686 ; 5687 numeric_tlr : 'END' 'LC_NUMERIC' EOL 5688 ; 5689 /* The following is the LC_TIME category grammar */ 5690 lc_time : time_hdr time_keywords time_tlr 5691 | time_hdr 'copy' locale_name EOL time_tlr 5692 ; 5693 time_hdr : 'LC_TIME' EOL 5694 ; Base Definitions, Issue 6 181 Locale Definition Grammar Locale 5695 time_keywords : time_keywords time_keyword 5696 | time_keyword 5697 ; 5698 time_keyword : time_keyword_name time_list EOL 5699 | time_keyword_fmt time_string EOL 5700 | time_keyword_opt time_list EOL 5701 ; 5702 time_keyword_name : 'abday' | 'day' | 'abmon' | 'mon' 5703 ; 5704 time_keyword_fmt : 'd_t_fmt' | 'd_fmt' | 't_fmt' 5705 | 'am_pm' | 't_fmt_ampm' 5706 ; 5707 time_keyword_opt : 'era' | 'era_d_fmt' | 'era_t_fmt' 5708 | 'era_d_t_fmt' | 'alt_digits' 5709 ; 5710 time_list : time_list ';' time_string 5711 | time_string 5712 ; 5713 time_string : '"' char_list '"' 5714 ; 5715 time_tlr : 'END' 'LC_TIME' EOL 5716 ; 182 Technical Standard (2000) (Draft July 28, 2000) Locale Locale Definition Example 5717 7.5 Locale Definition Example 5718 The following is an example of a locale definition file that could be used as input to the localedef 5719 utility. It assumes that the utility is executed with the -f option, naming a charmap file with (at 5720 least) the following content: 5721 CHARMAP 5722 \x20 5723 \x24 5724 \101 5725 \141 5726 \346 5727 \365 5728 \300 5729 \366 5730 \142 5731 \103 5732 \143 5733 \347 5734 \x64 5735 \110 5736 \150 5737 \xb7 5738 \x73 5739 \x7a 5740 END CHARMAP 5741 It should not be taken as complete or to represent any actual locale, but only to illustrate the 5742 syntax. 5743 # 5744 LC_CTYPE 5745 lower ;;;;;...; 5746 upper A;B;C;C,;...;Z 5747 space \x20;\x09;\x0a;\x0b;\x0c;\x0d 5748 blank \040;\011 5749 toupper (,);(b,B);(c,C);(c,,C,);(d,D);(z,Z) 5750 END LC_CTYPE 5751 # 5752 LC_COLLATE 5753 # 5754 # The following example of collation is based on 5755 # Canadian standard Z243.4.1-1998, "Canadian Alphanumeric 5756 # Ordering Standard For Character sets of CSA Z234.4 Standard". 5757 # (Other parts of this example locale definition file do not 5758 # purport to relate to Canada, or to any other real culture.) 5759 # The proposed standard defines a 4-weight collation, such that 5760 # in the first pass, characters are compared without regard to 5761 # case or accents; in second pass, backwards compare without 5762 # regard to case; in the third pass, forward compare without 5763 # regard to diacriticals. In the 3 first passes, non-alphabetic 5764 # characters are ignored; in the fourth pass, only special 5765 # characters are considered, such that "The string that has a 5766 # special character in the lowest position comes first. If two Base Definitions, Issue 6 183 Locale Definition Example Locale 5767 # strings have a special character in the same position, the 5768 # collation value of the special character determines ordering. 5769 # 5770 # Only a subset of the character set is used here; mostly to 5771 # illustrate the set-up. 5772 # 5773 collating-symbol 5774 collating-symbol 5775 collating-symbol 5776 collating-symbol 5777 collating-symbol 5778 collating-symbol 5779 collating-symbol 5780 collating-symbol 5781 collating-symbol 5782 collating-symbol 5783 collating-symbol 5784 # Further collating-symbols follow. 5785 # 5786 # Properly, the standard does not include any multi-character 5787 # collating elements; the one below is added for completeness. 5788 # 5789 collating_element from "" 5790 collating_element from "" 5791 collating_element from "" 5792 # 5793 order_start forward;backward;forward;forward,position 5794 # 5795 # Collating symbols are specified first in the sequence to allocate 5796 # basic collation values to them, lower than that of any character. 5797 5798 5799 5800 5801 5802 5803 5804 5805 5806 5807 5808 5809 5810 5811 # Further collating symbols are given a basic collating value here. 5812 # 5813 # Here follow special characters. 5814 IGNORE;IGNORE;IGNORE; 5815 # Other special characters follow here. 5816 # 5817 # Here follow the regular characters. 5818 ;;;IGNORE 184 Technical Standard (2000) (Draft July 28, 2000) Locale Locale Definition Example 5819 ;;;IGNORE 5820 ;;;IGNORE 5821 ;;;IGNORE 5822 ;;;IGNORE 5823 ;;;IGNORE 5824 "";"";\ 5825 "";IGNORE 5826 "";"";\ 5827 "";IGNORE 5828 ;;;IGNORE 5829 ;;;IGNORE 5830 ;;;IGNORE 5831 ;;;IGNORE 5832 ;;;IGNORE 5833 ;;;IGNORE 5834 ;;;IGNORE 5835 # 5836 # As an example, the strings "Bach" and "bach" could be encoded (for 5837 # compare purposes) as: 5838 # "Bach" ;;;;;;\ 5839 # ;;;;\ 5840 # ; 5841 # "bach" ;;;;;;\ 5842 # ;;;;\ 5843 # ; 5844 # 5845 # The two strings are equal in pass 1 and 2, but differ in pass 3. 5846 # 5847 # Further characters follow. 5848 # 5849 UNDEFINED IGNORE;IGNORE;IGNORE;IGNORE 5850 # 5851 order_end 5852 # 5853 END LC_COLLATE 5854 # 5855 LC_MONETARY 5856 int_curr_symbol "USD " 5857 currency_symbol "$" 5858 mon_decimal_point "." 5859 mon_grouping 3;0 5860 positive_sign "" 5861 negative_sign "-" 5862 p_cs_precedes 1 5863 n_sign_posn 0 5864 END LC_MONETARY 5865 # 5866 LC_NUMERIC 5867 copy "US_en.ASCII" 5868 END LC_NUMERIC 5869 # 5870 LC_TIME Base Definitions, Issue 6 185 Locale Definition Example Locale 5871 abday "Sun";"Mon";"Tue";"Wed";"Thu";"Fri";"Sat" 5872 # 5873 day "Sunday";"Monday";"Tuesday";"Wednesday";\ 5874 "Thursday";"Friday";"Saturday" 5875 # 5876 abmon "Jan";"Feb";"Mar";"Apr";"May";"Jun";\ 5877 "Jul";"Aug";"Sep";"Oct";"Nov";"Dec" 5878 # 5879 mon "January";"February";"March";"April";\ 5880 "May";"June";"July";"August";"September";\ 5881 "October";"November";"December" 5882 # 5883 d_t_fmt "%a %b %d %T %Z %Y\n" 5884 END LC_TIME 5885 # 5886 LC_MESSAGES 5887 yesexpr " ([yY][[:alpha:]]*)|(OK)" 5888 # 5889 noexpr " [nN][[:alpha:]]*" 5890 END LC_MESSAGES | 186 Technical Standard (2000) (Draft July 28, 2000) Chapter 8 Environment Variables 5891 5892 8.1 Environment Variable Definition 5893 Environment variables defined in this chapter affect the operation of multiple utilities, functions, 5894 and applications. There are other environment variables that are of interest only to specific 5895 utilities. Environment variables that apply to a single utility only are defined as part of the 5896 utility description. See the ENVIRONMENT VARIABLES section of the utility descriptions in | 5897 the Shell and Utilities volume of IEEE Std. 1003.1-200x for information on environment variable | 5898 usage. 5899 The value of an environment variable is a string of characters. For a C-language program, an 5900 array of strings called the environment is made available when a process begins. The array is 5901 pointed to by the external variable environ, which is defined as: 5902 extern char **environ; 5903 These strings have the form name=value; names do not contain the character '='. For values to 5904 be portable across systems conforming to IEEE Std. 1003.1-200x, the value shall be composed of 5905 characters from the portable character set (except NUL and as indicated below). There is no 5906 meaning associated with the order of strings in the environment. If more than one string in a 5907 process' environment has the same name, the consequences are undefined. 5908 Environment variable names used by the utilities in the Shell and Utilities volume of | 5909 IEEE Std. 1003.1-200x shall consist solely of uppercase letters, digits, and the '_' (underscore) | 5910 from the characters defined in Table 6-1 (on page 133). Other characters may be permitted by an 5911 implementation; applications shall tolerate the presence of such names. Uppercase and 5912 lowercase letters retain their unique identities and are not folded together. The name space of 5913 environment variable names containing lowercase letters is reserved for applications. 5914 Applications can define any environment variables with names from this name space without 5915 modifying the behavior of the standard utilities. 5916 The values that the environment variables may be assigned are not restricted except that they are 5917 considered to end with a null byte and the total space used to store the environment and the 5918 arguments to the process is limited to {ARG_MAX} bytes. 5919 Other name=value pairs may be placed in the environment by, for example, calling any of the 5920 XSI setenv( ), unsetenv( ), or putenv( ) functions, manipulating the environ variable, or by using envp 5921 arguments when creating a process; see exec in the System Interfaces volume of 5922 IEEE Std. 1003.1-200x. 5923 It is unwise to conflict with certain variables that are frequently exported by widely used 5924 command interpreters and applications: Base Definitions, Issue 6 187 Environment Variable Definition Environment Variables 5925 __________________________________________________________ 5926 ARFLAGS IFS MAILPATH PS1 5927 CC LANG MAILRC PS2 5928 CDPATH LC_ALL MAKEFLAGS PS3 5929 CFLAGS LC_COLLATE MAKESHELL PS4 5930 CHARSET LC_CTYPE MANPATH PWD 5931 COLUMNS LC_MESSAGES MBOX RANDOM 5932 DATEMSK LC_MONETARY MORE SECONDS 5933 DEAD LC_NUMERIC MSGVERB SHELL 5934 EDITOR LC_TIME NLSPATH TERM 5935 ENV LDFLAGS NPROC TERMCAP 5936 EXINIT LEX OLDPWD TERMINFO 5937 FC LFLAGS OPTARG TMPDIR 5938 FCEDIT LINENO OPTERR TZ 5939 FFLAGS LINES OPTIND USER 5940 GET LISTER PAGER VISUAL 5941 GFLAGS LOGNAME PATH YACC 5942 HISTFILE LPDEST PPID YFLAGS 5943 HISTORY MAIL PRINTER 5944 HISTSIZE MAILCHECK PROCLANG 5945 _ HOME MAILER PROJECTDIR _________________________________________________________ 5946 If the variables in the following two sections are present in the environment during the 5947 execution of an application or utility, they are given the meaning described below. Some are 5948 placed into the environment by the implementation at the time the user logs in; all can be added 5949 or changed by the user or any ancestor of the current process. The implementation adds or 5950 changes environment variables named in IEEE Std. 1003.1-200x only as specified in 5951 IEEE Std. 1003.1-200x. If they are defined in the application's environment, the utilities in the | 5952 Shell and Utilities volume of IEEE Std. 1003.1-200x and the functions in the System Interfaces | 5953 volume of IEEE Std. 1003.1-200x assume they have the specified meaning. Conforming | 5954 applications shall not set these environment variables to have meanings other than as described. 5955 See getenv( ) and the Shell and Utilities volume of IEEE Std. 1003.1-200x, Section 2.13, Shell | 5956 Execution Environment for methods of accessing these variables. | 188 Technical Standard (2000) (Draft July 28, 2000) Environment Variables Internationalization Variables 5957 8.2 Internationalization Variables 5958 This section describes environment variables that are relevant to the operation of 5959 internationalized interfaces described in the System Interfaces volume of IEEE Std. 1003.1-200x 5960 and the Shell and Utilities volume of IEEE Std. 1003.1-200x. | 5961 Users may use the following environment variables to announce specific localization 5962 requirements to applications. Applications shall retrieve this information using the setlocale( ) 5963 function to initialize the correct behavior of the internationalized interfaces. The descriptions of 5964 the internationalization environment variables describe the resulting behavior only when the 5965 application locale is initialized in this way. 5966 LANG This variable shall determine the locale category for native language, local 5967 customs, and coded character set in the absence of the LC_ALL and other LC_* | 5968 (LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, LC_NUMERIC, 5969 LC_TIME) environment variables. This can be used by applications to 5970 determine the language to use for error messages and instructions, collating 5971 sequences, date formats, and so on. 5972 LC_ALL This variable shall determine the values for all locale categories. The value of 5973 the LC_ALL environment variable has precedence over any of the other 5974 environment variables starting with LC_(LC_COLLATE, LC_CTYPE, 5975 LC_MESSAGES, LC_MONETARY, LC_NUMERIC, LC_TIME) and the LANG 5976 environment variable. 5977 LC_COLLATE This variable shall determine the locale category for character collation. It 5978 determines collation information for regular expressions and sorting, 5979 including equivalence classes and multi-character collating elements, in 5980 various utilities and the strcoll( ) and strxfrm( ) functions. Additional semantics 5981 of this variable, if any, are implementation-defined. | 5982 LC_CTYPE This variable shall determine the locale category for character handling 5983 functions, such as tolower( ), toupper( ), and isalpha( ). This environment 5984 variable determines the interpretation of sequences of bytes of text data as 5985 characters (for example, single as opposed to multi-byte characters), the 5986 classification of characters (for example, alpha, digit, graph), and the behavior 5987 of character classes. Additional semantics of this variable, if any, are | 5988 implementation-defined. | 5989 LC_MESSAGES This variable shall determine the locale category for processing affirmative 5990 and negative responses and the language and cultural conventions in which 5991 XSI messages should be written. It also affects the behavior of the catopen( ) 5992 function in determining the message catalog. Additional semantics of this 5993 variable, if any, are implementation-defined. The language and cultural | 5994 conventions of diagnostic and informative messages whose format is | 5995 unspecified by IEEE Std. 1003.1-200x should be affected by the setting of 5996 LC_MESSAGES. 5997 LC_MONETARY This variable shall determine the locale category for monetary-related numeric 5998 formatting information. Additional semantics of this variable, if any, are | 5999 implementation-defined. | 6000 LC_NUMERIC This variable shall determine the locale category for numeric formatting (for 6001 example, thousands separator and radix character) information in various 6002 utilities as well as the formatted I/O operations in printf( ) and scanf( ) and the 6003 string conversion functions in strtod( ). Additional semantics of this variable, 6004 if any, are implementation-defined. | Base Definitions, Issue 6 189 Internationalization Variables Environment Variables 6005 LC_TIME This variable shall determine the locale category for date and time formatting 6006 information. It affects the behavior of the time functions in strftime( ). 6007 Additional semantics of this variable, if any, are implementation-defined. | 6008 XSI NLSPATH This variable shall contain a sequence of templates that the catopen( ) function 6009 uses when attempting to locate message catalogs. Each template consists of an 6010 optional prefix, one or more substitution fields, a file name, and an optional 6011 suffix. 6012 For example: 6013 NLSPATH="/system/nlslib/%N.cat" 6014 defines that catopen( ) should look for all message catalogs in the directory 6015 /system/nlslib, where the catalog name should be constructed from the name 6016 parameter passed to catopen( ) (%N), with the suffix .cat. 6017 Substitution fields consist of a '%' symbol, followed by a single-letter 6018 keyword. The following keywords are currently defined: 6019 %N The value of the name parameter passed to catopen( ). 6020 %L The value of the LC_MESSAGES category. 6021 %l The language element from the LC_MESSAGES category. 6022 %t The territory element from the LC_MESSAGES category. 6023 %c The codeset element from the LC_MESSAGES category. 6024 %% A single '%' character. 6025 An empty string is substituted if the specified value is not currently defined. 6026 The separators underscore ('_') and period ('.') are not included in %t and 6027 %c substitutions. 6028 Templates defined in NLSPATH are separated by colons (':'). A leading or 6029 two adjacent colons "::" is equivalent to specifying %N. For example: 6030 NLSPATH=":%N.cat:/nlslib/%L/%N.cat" 6031 indicates to catopen( ) that it should look for the requested message catalog in 6032 name, name.cat, and /nlslib/category/name.cat, where category is the value of the 6033 LC_MESSAGES category of the current locale. 6034 Users should not set the NLSPATH variable unless they have a specific reason 6035 to override the default system path. Doing so causes undefined behavior in 6036 the standard utilities. 6037 The environment variables LANG, LC_ALL, LC_COLLATE, LC_CTYPE, LC_MESSAGES, 6038 XSI LC_MONETARY, LC_NUMERIC, LC_TIME, and NLSPATH provide for the support of 6039 internationalized applications. The standard utilities shall make use of these environment 6040 variables as described in this section and the individual ENVIRONMENT VARIABLES sections 6041 for the utilities. If these variables specify locale categories that are not based upon the same 6042 underlying codeset, the results are unspecified. 6043 The values of locale categories shall be determined by a precedence order; the first condition met 6044 below determines the value: 6045 1. If the LC_ALL environment variable is defined and is not null, the value of LC_ALL shall be 6046 used. 190 Technical Standard (2000) (Draft July 28, 2000) Environment Variables Internationalization Variables 6047 2. If the LC_* environment variable (LC_COLLATE, LC_CTYPE, LC_MESSAGES, 6048 LC_MONETARY, LC_NUMERIC, LC_TIME) is defined and is not null, the value of the 6049 environment variable shall be used to initialize the category that corresponds to the 6050 environment variable. 6051 3. If the LANG environment variable is defined and is not null, the value of the LANG 6052 environment variable shall be used. 6053 4. If the LANG environment variable is not set or is set to the empty string, the | 6054 implementation-defined default locale shall be used. | 6055 If the locale value is "C" or "POSIX", the POSIX locale shall be used and the standard utilities 6056 behave in accordance with the rules in Section 7.2 (on page 144) for the associated category. 6057 If the locale value begins with a slash, it shall be interpreted as the path name of a file that was 6058 created in the output format used by the localedef utility; see OUTPUT FILES under localedef. 6059 Referencing such a path name results in that locale being used for the indicated category. 6060 XSI If the locale value has the form: 6061 language[_territory][.codeset] 6062 it refers to an implementation-provided locale, where settings of language, territory, and codeset | 6063 are implementation-defined. | 6064 LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, LC_NUMERIC, and LC_TIME are 6065 defined to accept an additional field @modifier, which allows the user to select a specific instance 6066 of localization data within a single category (for example, for selecting the dictionary as opposed 6067 to the character ordering of data). The syntax for these environment variables is thus defined as: 6068 [language[_territory][.codeset][@modifier]] 6069 For example, if a user wanted to interact with the system in French, but required to sort German 6070 text files, LANG and LC_COLLATE could be defined as: 6071 LANG=Fr_FR 6072 LC_COLLATE=De_DE 6073 This could be extended to select dictionary collation (say) by use of the @modifier field; for 6074 example: 6075 LC_COLLATE=De_DE@dict 6076 6077 An implementation may support other formats. 6078 If the locale value is not recognized by the implementation, the behavior is unspecified. 6079 At runtime, these values are bound to a program's locale by calling the setlocale( ) function. 6080 Additional criteria for determining a valid locale name are implementation-defined. | Base Definitions, Issue 6 191 Other Environment Variables Environment Variables 6081 8.3 Other Environment Variables 6082 COLUMNS This variable shall represent a decimal integer >0 used to indicate the user's 6083 preferred width in column positions for the terminal screen or window; see 6084 Section 3.106 (on page 59). If this variable is unset or null, the implementation 6085 determines the number of columns, appropriate for the terminal or window, 6086 in an unspecified manner. When COLUMNS is set, any terminal-width 6087 information implied by TERM is overridden. Users and portable applications 6088 should not set COLUMNS unless they wish to override the system selection 6089 and produce output unrelated to the terminal characteristics. 6090 Users should not need to set this variable in the environment unless there is a 6091 specific reason to override the implementation's default behavior, such as to 6092 display data in an area arbitrarily smaller than the terminal or window. 6093 XSI DATEMSK Indicates the path name of the template file used by getdate( ). 6094 HOME The system initializes this variable at the time of login to be a path name of the 6095 user's home directory. See . | 6096 LINES This variable shall represent a decimal integer >0 used to indicate the user's 6097 preferred number of lines on a page or the vertical screen or window size in 6098 lines. A line in this case is a vertical measure large enough to hold the tallest 6099 character in the character set being displayed. If this variable is unset or null, 6100 the implementation determines the number of lines, appropriate for the 6101 terminal or window (size, terminal baud rate, and so on), in an unspecified 6102 manner. When LINES is set, any terminal-height information implied by 6103 TERM is overridden. Users and portable applications should not set LINES 6104 unless they wish to override the system selection and produce output 6105 unrelated to the terminal characteristics. 6106 Users should not need to set this variable in the environment unless there is a 6107 specific reason to override the implementation's default behavior, such as to 6108 display data in an area arbitrarily smaller than the terminal or window. 6109 LOGNAME The system initializes this variable at the time of login to be the user's login | 6110 name. See . For a value of LOGNAME to be portable across 6111 implementations of IEEE Std. 1003.1-200x, the value should be composed of 6112 characters from the portable file name character set. 6113 XSI MSGVERB Describes which message components shall be used in writing messages by 6114 fmtmsg( ). 6115 PATH This variable shall represent the sequence of path prefixes that certain 6116 functions and utilities apply in searching for an executable file known only by 6117 a file name. The prefixes are separated by a colon (':'). When a non-zero- 6118 length prefix is applied to this file name, a slash is inserted between the prefix 6119 and the file name. A zero-length prefix is a legacy feature that indicates the 6120 current working directory. It appears as two adjacent colons ("::"), as an 6121 initial colon preceding the rest of the list, or as a trailing colon following the 6122 rest of the list. A portable application shall use an actual path name (such as .) 6123 to represent the current working directory in PATH. The list is searched from 6124 beginning to end, applying the file name to each prefix, until an executable file 6125 with the specified name and appropriate execution permissions is found. If 6126 the path name being sought contains a slash, the search through the path 6127 prefixes is not performed. If the path name begins with a slash, the specified 6128 path is resolved (see Section 4.9 (on page 123)). If PATH is unset or is set to 192 Technical Standard (2000) (Draft July 28, 2000) Environment Variables Other Environment Variables 6129 null, the path search is implementation-defined. | 6130 PWD This variable shall represent an absolute path name of the current working 6131 directory. It shall not contain any file name components of dot or dot-dot. The 6132 value is set by the cd utility. 6133 SHELL This variable shall represent a path name of the user's preferred command 6134 language interpreter. If this interpreter does not conform to the Shell | 6135 Command Language in the Shell and Utilities volume of | 6136 IEEE Std. 1003.1-200x, Chapter 2, Shell Command Language, utilities may | 6137 behave differently from those described in IEEE Std. 1003.1-200x. | 6138 TMPDIR This variable shall represent a path name of a directory made available for 6139 programs that need a place to create temporary files. 6140 TERM This variable shall represent the terminal type for which output is to be 6141 prepared. This information is used by utilities and application programs 6142 wishing to exploit special capabilities specific to a terminal. The format and 6143 allowable values of this environment variable are unspecified. 6144 TZ This variable shall represent timezone information. The contents of the 6145 environment variable named TZ shall be used by the ctime( ), localtime( ), 6146 strftime( ), and mktime( ) functions, and by various utilities, to override the 6147 default timezone. The value of TZ has one of the two forms (spaces inserted 6148 for clarity): 6149 :characters 6150 or: 6151 std offset dst offset, rule 6152 If TZ is of the first format (that is, if the first character is a colon), the 6153 characters following the colon are handled in an implementation-defined | 6154 manner. | 6155 The expanded format (for all TZs whose value does not have a colon as the 6156 first character) is as follows: 6157 stdoffset[dst[offset][,start[/time],end[/time]]] 6158 Where: 6159 std and dst Indicate no less than three, nor more than {TZNAME_MAX}, 6160 bytes that are the designation for the standard (std) or the 6161 alternative (dst-such as Daylight Savings Time) timezone. Only 6162 std is required; if dst is missing, then the alternative time does 6163 not apply in this locale. 6164 Each of these fields may occur in either of two formats quoted or 6165 unquoted: 6166 - In the quoted form, the first character shall be the less-than 6167 ('<') character and the last character shall be the greater- 6168 than ('>') character. All characters between these quoting 6169 characters shall be alphanumeric characters in the current 6170 locale, the plus-sign ('+') character, or the minus-sign ('-') 6171 character. The std and dst fields in this case do not include the 6172 quoting characters. Base Definitions, Issue 6 193 Other Environment Variables Environment Variables 6173 - In the unquoted form, all characters in these fields shall be 6174 alphabetic characters in the current locale. 6175 The interpretation of these fields is unspecified if either field is 6176 less than three bytes (except for the case when dst is missing), 6177 more than {TZNAME_MAX} bytes, or if they contain characters 6178 other than those specified. 6179 offset Indicates the value added to the local time to arrive at 6180 Coordinated Universal Time. The offset has the form: 6181 hh[:mm[:ss]] 6182 The minutes (mm) and seconds (ss) are optional. The hour (hh) 6183 shall be required and may be a single digit. The offset following 6184 std shall be required. If no offset follows dst, the alternative time 6185 is assumed to be one hour ahead of standard time. One or more 6186 digits may be used; the value is always interpreted as a decimal 6187 number. The hour shall be between zero and 24, and the minutes 6188 (and seconds)-if present-between zero and 59. The result of 6189 using values outside of this range is unspecified. If preceded by 6190 a '-', the timezone shall be east of the Prime Meridian; 6191 otherwise, it shall be west (which may be indicated by an 6192 optional preceding '+'). 6193 rule Indicates when to change to and back from the alternative time. 6194 The rule has the form: 6195 date[/time],date[/time] 6196 where the first date describes when the change from standard to 6197 alternative time occurs and the second date describes when the 6198 change back happens. Each time field describes when, in current 6199 local time, the change to the other time is made. 6200 The format of date is one of the following: | 6201 Jn The Julian day n (1 n 365). Leap days shall not be | 6202 counted. That is, in all years-including leap years- 6203 February 28 is day 59 and March 1 is day 60. It is 6204 impossible to refer explicitly to the occasional February 6205 29. 6206 n The zero-based Julian day (0 n 365). Leap days shall 6207 be counted, and it is possible to refer to February 29. 6208 Mm.n.d The d'th day (0 d 6) of week n of month m of the 6209 year (1 n 5, 1 m 12, where week 5 means ``the 6210 last d day in month m'' which may occur in either the 6211 fourth or the fifth week). Week 1 is the first week in 6212 which the d'th day occurs. Day zero is Sunday. 6213 The time has the same format as offset except that no leading sign 6214 ('-' or '+') is allowed. The default, if time is not given, shall be 6215 02:00:00. | 6216 | 194 Technical Standard (2000) (Draft July 28, 2000) Chapter 9 Regular Expressions 6217 6218 Regular Expressions (REs) provide a mechanism to select specific strings from a set of character 6219 strings. 6220 Regular expressions are a context-independent syntax that can represent a wide variety of 6221 character sets and character set orderings, where these character sets are interpreted according 6222 to the current locale. While many regular expressions can be interpreted differently depending 6223 on the current locale, many features, such as character class expressions, provide for contextual 6224 invariance across locales. 6225 The Basic Regular Expression (BRE) notation and construction rules in Section 9.3 (on page 198) 6226 shall apply to most utilities supporting regular expressions. Some utilities, instead, support the 6227 Extended Regular Expressions (ERE) described in Section 9.4 (on page 203); any exceptions for 6228 both cases are noted in the descriptions of the specific utilities using regular expressions. Both 6229 BREs and EREs are supported by the Regular Expression Matching interface in the System 6230 Interfaces volume of IEEE Std. 1003.1-200x under regcomp( ), regexec( ), and related functions. | Base Definitions, Issue 6 195 Regular Expression Definitions Regular Expressions 6231 9.1 Regular Expression Definitions 6232 For the purposes of this section, the following definitions shall apply: 6233 entire regular expression 6234 The concatenated set of one or more BREs or EREs that make up the pattern specified for 6235 string selection. 6236 matched 6237 A sequence of zero or more characters shall be said to be matched by a BRE or ERE when 6238 the characters in the sequence correspond to a sequence of characters defined by the 6239 pattern. 6240 Matching shall be based on the bit pattern used for encoding the character, not on the 6241 graphic representation of the character. This means that if a character set contains two or 6242 more encodings for a graphic symbol, or if the strings searched contain text encoded in 6243 more than one codeset, no attempt is made to search for any other representation of the 6244 encoded symbol. If that is required, the user can specify equivalence classes containing all 6245 variations of the desired graphic symbol. 6246 The search for a matching sequence starts at the beginning of a string and stops when the 6247 first sequence matching the expression is found, where first is defined to mean ``begins 6248 earliest in the string''. If the pattern permits a variable number of matching characters and 6249 thus there is more than one such sequence starting at that point, the longest such sequence 6250 is matched. For example: the BRE "bb*" matches the second to fourth characters of abbbc, 6251 and the ERE (wee|week)(knights|night) matches all ten characters of weeknights. 6252 Consistent with the whole match being the longest of the leftmost matches, each subpattern, 6253 from left to right, shall match the longest possible string. For this purpose, a null string shall 6254 be considered to be longer than no match at all. For example, matching the BRE 6255 "\(.*\).*" against "abcdef", the subexpression "(\1)" is "abcdef", and matching 6256 the BRE "\(a*\)*" against "bc", the subexpression "(\1)" is the null string. 6257 When a multi-character collating element in a bracket expression (see Section 9.3.5 (on page 6258 199)) is involved, the longest sequence shall be measured in characters consumed from the 6259 string to be matched; that is, the collating element counts not as one element, but as the 6260 number of characters it matches. | 6261 BRE (ERE) matching a single character 6262 A BRE or ERE that shall match either a single character or a single collating element. 6263 Only a BRE or ERE of this type that includes a bracket expression (see Section 9.3.5 (on page 6264 199)) can match a collating element. | 6265 BRE (ERE) matching multiple characters 6266 A BRE or ERE that shall match a concatenation of single characters or collating elements. 6267 Such a BRE or ERE is made up from a BRE (ERE) matching a single character and BRE (ERE) 6268 special characters. 6269 invalid 6270 This section uses the term invalid for certain constructs or conditions. Invalid REs shall 6271 cause the utility or function using the RE to generate an error condition. When invalid is not 6272 used, violations of the specified syntax or semantics for REs produce undefined results: this 6273 may entail an error, enabling an extended syntax for that RE, or using the construct in error 6274 as literal characters to be matched. For example, the BRE construct "\{1,2,3\}" does not 6275 comply with the grammar. A portable application cannot rely on it producing an error nor 6276 matching the literal characters "\{1,2,3\}". 196 Technical Standard (2000) (Draft July 28, 2000) Regular Expressions Regular Expression Definitions 6277 9.2 Regular Expression General Requirements 6278 The requirements in this section shall apply to both basic and extended regular expressions. 6279 The use of regular expressions is generally associated with text processing. REs (BREs and EREs) 6280 operate on text strings; that is, zero or more characters followed by an end-of-string delimiter 6281 (typically NUL). Some utilities employing regular expressions limit the processing to lines; that 6282 is, zero or more characters followed by a character. In the regular expression 6283 processing described in IEEE Std. 1003.1-200x, the character is regarded as an 6284 ordinary character and both a period and a non-matching list can match one. The Shell and | 6285 Utilities volume of IEEE Std. 1003.1-200x specifies within the individual descriptions of those | 6286 standard utilities employing regular expressions whether they permit matching of 6287 characters; if not stated otherwise, the use of literal characters or any escape sequence 6288 equivalent produces undefined results. Those utilities (like grep) that do not allow 6289 characters to match are responsible for eliminating any character from strings before 6290 matching against the RE. The regcomp( ) function in the System Interfaces volume of 6291 IEEE Std. 1003.1-200x, however, can provide support for such processing without violating the 6292 rules of this section. 6293 The interfaces specified in IEEE Std. 1003.1-200x do not permit the inclusion of a NUL character 6294 in an RE or in the string to be matched. If during the operation of a standard utility a NUL is 6295 included in the text designated to be matched, that NUL may designate the end of the text string 6296 for the purposes of matching. 6297 When a standard utility or function that uses regular expressions specifies that pattern matching 6298 shall be performed without regard to the case (uppercase or lowercase) of either data or 6299 patterns, then when each character in the string is matched against the pattern, not only the 6300 character, but also its case counterpart (if any), shall be matched. This definition of case- 6301 insensitive processing is intended to allow matching of multi-character collating elements as 6302 well as characters. For example, as each character in the string is matched using both its cases, 6303 the RE "[[.Ch.]]" when matched against the string "char", is in reality matched against 6304 "ch", "Ch", "cH", and "CH". 6305 The implementation shall support any regular expression that does not exceed 256 bytes in 6306 length. | Base Definitions, Issue 6 197 Basic Regular Expressions Regular Expressions 6307 9.3 Basic Regular Expressions 6308 9.3.1 BREs Matching a Single Character or Collating Element 6309 A BRE ordinary character, a special character preceded by a backslash or a period, shall match a 6310 single character. A bracket expression shall match a single character or a single collating 6311 element. 6312 9.3.2 BRE Ordinary Characters 6313 An ordinary character is a BRE that matches itself: any character in the supported character set, 6314 except for the BRE special characters listed in Section 9.3.3. 6315 The interpretation of an ordinary character preceded by a backslash ('\') is undefined, except 6316 for: 6317 * The characters ')', '(', '{', and '}' 6318 * The digits 1 to 9 inclusive (see Section 9.3.6 (on page 201)) 6319 * A character inside a bracket expression 6320 9.3.3 BRE Special Characters 6321 A BRE special character has special properties in certain contexts. Outside those contexts, or when 6322 preceded by a backslash, such a character is a BRE that matches the special character itself. The 6323 BRE special characters and the contexts in which they have their special meaning are as follows: 6324 . [ \ The period, left-bracket, and backslash shall be special except when used in a bracket 6325 expression (see Section 9.3.5 (on page 199)). An expression containing a '[' that is not 6326 preceded by a backslash and is not part of a bracket expression produces undefined 6327 results. 6328 * The asterisk shall be special except when used: 6329 * In a bracket expression 6330 * As the first character of an entire BRE (after an initial ' ', if any) 6331 * As the first character of a subexpression (after an initial ' ', if any); see Section 6332 9.3.6 (on page 201) 6333 ^ The circumflex shall be special when used as: 6334 * An anchor (see Section 9.3.8 (on page 202)) 6335 * The first character of a bracket expression (see Section 9.3.5 (on page 199)) 6336 $ The dollar sign shall be special when used as an anchor. 6337 9.3.4 Periods in BREs 6338 A period ('.'), when used outside a bracket expression, is a BRE that shall match any character 6339 in the supported character set except NUL. 198 Technical Standard (2000) (Draft July 28, 2000) Regular Expressions Basic Regular Expressions 6340 9.3.5 RE Bracket Expression 6341 A bracket expression (an expression enclosed in square brackets, "[ ]") is an RE that matches a 6342 single collating element contained in the non-empty set of collating elements represented by the 6343 bracket expression. 6344 The following rules and definitions apply to bracket expressions: 6345 1. A bracket expression is either a matching list expression or a non-matching list expression. It 6346 consists of one or more expressions: collating elements, collating symbols, equivalence 6347 classes, character classes, or range expressions. Portable applications shall not use range 6348 expressions, even though all implementations shall support them. The right-bracket (']') 6349 shall lose its special meaning and represents itself in a bracket expression if it occurs first in 6350 the list (after an initial circumflex (' '), if any). Otherwise, it shall terminate the bracket 6351 expression, unless it appears in a collating symbol (such as "[.].]") or is the ending 6352 right-bracket for a collating symbol, equivalence class, or character class. The special 6353 characters '.', '*', '[', and '\' (period, asterisk, left-bracket, and backslash, 6354 respectively) shall lose their special meaning within a bracket expression. 6355 The character sequences "[.", "[=", and "[:" (left-bracket followed by a period, equals- 6356 sign, or colon) shall be special inside a bracket expression and are used to delimit collating 6357 symbols, equivalence class expressions, and character class expressions. These symbols 6358 shall be followed by a valid expression and the matching terminating sequence ".]", 6359 "=]", or ":]", as described in the following items. 6360 2. A matching list expression specifies a list that shall match any one of the expressions 6361 represented in the list. The first character in the list shall not be the circumflex; for 6362 example, "[abc]" is an RE that matches any of the characters 'a', 'b', or 'c'. 6363 3. A non-matching list expression begins with a circumflex (' '), and specifies a list that shall 6364 match any character or collating element except for the expressions represented in the list 6365 after the leading circumflex. For example, "[ abc]" is an RE that matches any character 6366 or collating element except the characters 'a', 'b', or 'c'. The circumflex shall have this 6367 special meaning only when it occurs first in the list, immediately following the left-bracket. 6368 4. A collating symbol is a collating element enclosed within bracket-period ("[." and ".]") 6369 delimiters. Collating elements are defined as described in Section 7.3.2.4 (on page 158). 6370 Portable applications shall represent multi-character collating elements as collating 6371 symbols when it is necessary to distinguish them from a list of the individual characters 6372 that make up the multi-character collating element. For example, if the string "ch" is a 6373 collating element in the current collation sequence with the associated collating symbol 6374 , the expression "[[.ch.]]" shall be treated as an RE matching the character 6375 sequence 'ch', while "[ch]" shall be treated as an RE matching 'c' or 'h'. Collating 6376 symbols are recognized only inside bracket expressions. This implies that the RE 6377 "[[.ch.]]*c" shall match the first to fifth character in the string "chchch". If the string 6378 is not a collating element in the current collating sequence definition, or if the collating 6379 element has no characters associated with it (for example, see the symbol in the 6380 example collation definition shown in Section 7.3.2.2 (on page 157)), the symbol shall be 6381 treated as an invalid expression. 6382 5. An equivalence class expression shall represent the set of collating elements belonging to an 6383 equivalence class, as described in Section 7.3.2.4 (on page 158). Only primary equivalence 6384 classes shall be recognized. The class shall be expressed by enclosing any one of the 6385 collating elements in the equivalence class within bracket-equal ("[=" and "=]") 6386 delimiters. For example, if 'a', 'à', and 'â' belong to the same equivalence class, then 6387 "[[=a=]b]", "[[=à=]b]", and "[[=â=]b]" are each equivalent to "[aàâb]". If the Base Definitions, Issue 6 199 Basic Regular Expressions Regular Expressions 6388 collating element does not belong to an equivalence class, the equivalence class expression 6389 shall be treated as a collating symbol. 6390 6. A character class expression shall represent the set of characters belonging to a character 6391 class, as defined in the LC_CTYPE category in the current locale. All character classes 6392 specified in the current locale shall be recognized. A character class expression is expressed 6393 as a character class name enclosed within bracket-colon ("[:" and ":]") delimiters. 6394 The following character class expressions shall be supported in all locales: 6395 [:alnum:] [:cntrl:] [:lower:] [:space:] 6396 [:alpha:] [:digit:] [:print:] [:upper:] 6397 [:blank:] [:graph:] [:punct:] [:xdigit:] 6398 XSI In addition, character class expressions of the form: 6399 [:name:] 6400 are recognized in those locales where the name keyword has been given a charclass 6401 definition in the LC_CTYPE category. 6402 7. A range expression represents the set of collating elements that fall between two elements 6403 in the collating element order of the current locale, inclusive. A range expression shall be 6404 expressed as the starting point and the ending point separated by a hyphen ('-'). 6405 Range expressions shall not be used in portable applications because their behavior is | 6406 dependent on the collating sequence. | 6407 In the following, all examples assume the collation sequence specified for the POSIX locale, 6408 unless another collation sequence is specifically defined. 6409 The starting range point and the ending range point shall be a collating element or 6410 collating symbol. An equivalence class expression used as a starting or ending point of a 6411 range expression produces unspecified results. An equivalence class can be used portably 6412 within a bracket expression, but only outside the range. For example, the unspecified 6413 expression "[[=e=]-f]" should be given as "[[=e=]e-f]". The ending range point 6414 shall collate equal to or higher than the starting range point; otherwise, the expression is 6415 treated as invalid. The order used is the order in which the collating elements are specified 6416 in the current collation definition. One-to-many mappings (see the description of 6417 LC_COLLATE in Section 7.3.2 (on page 155)) are not performed. For example, assuming 6418 that the character eszet (' ') is placed in the collation sequence after 'r' and 's', but 6419 before 't' and that it maps to the sequence "ss" for collation purposes, then the 6420 expression "[r-s]" matches only 'r' and 's', but the expression "[s-t]" matches 6421 's', ' ', or 't'. 6422 The interpretation of range expressions where the ending range point is also the starting 6423 range point of a subsequent range expression (for example, "[a-m-o]") is undefined. 6424 The hyphen character shall be treated as itself if it occurs first (after an initial ' ', if any) 6425 or last in the list, or as an ending range point in a range expression. As examples, the 6426 expressions "[-ac]" and "[ac-]" are equivalent and match any of the characters 'a', 6427 'c', or '-'; "[ -ac]" and "[ ac-]" are equivalent and match any characters except 6428 'a', 'c', or '-'; the expression "[%--]" matches any of the characters between '%' and 6429 '-' inclusive; the expression "[--@]" matches any of the characters between '-' and 6430 '@' inclusive; and the expression "[a- -@]" is invalid, because the letter 'a' follows the 6431 symbol '-' in the POSIX locale. To use a hyphen as the starting range point, it shall either 6432 come first in the bracket expression or be specified as a collating symbol; for example, 6433 "[][.-.]-0]", which matches either a right bracket or any character or collating element 200 Technical Standard (2000) (Draft July 28, 2000) Regular Expressions Basic Regular Expressions 6434 that collates between hyphen and 0, inclusive. 6435 If a bracket expression specifies both '-' and ']', the ']' shall be placed first (after the 6436 ' ', if any) and the '-' last within the bracket expression. 6437 9.3.6 BREs Matching Multiple Characters 6438 The following rules can be used to construct BREs matching multiple characters from BREs 6439 matching a single character: 6440 1. The concatenation of BREs shall match the concatenation of the strings matched by each 6441 component of the BRE. 6442 2. A subexpression can be defined within a BRE by enclosing it between the character pairs 6443 "\(" and "\)". Such a subexpression shall match whatever it would have matched 6444 without the "\(" and "\)", except that anchoring within subexpressions is optional 6445 behavior; see Section 9.3.8 (on page 202). Subexpressions can be arbitrarily nested. 6446 3. The back-reference expression '\n' shall match the same (possibly empty) string of 6447 characters as was matched by a subexpression enclosed between "\(" and "\)" 6448 preceding the '\n'. The character 'n' shall be a digit from 1 through 9, specifying the 6449 nth subexpression (the one that begins with the nth "\(" from the beginning of the | 6450 pattern and ends with the corresponding paired "\)"). The expression is invalid if less | 6451 than n subexpressions precede the '\n'. For example, the expression "\(.*\)\1$" | 6452 matches a line consisting of two adjacent appearances of the same string, and the 6453 expression "\(a\)*\1" fails to match 'a'. When the referenced subexpression matched 6454 more than one string, the back-referenced expression shall refer to the last matched string. 6455 If the subexpression referenced by the back-reference matches more than one string 6456 because of an asterisk ('*') or an interval expression (see item (5)), the back-reference 6457 shall match the last (rightmost) of these strings. 6458 4. When a BRE matching a single character, a subexpression, or a back-reference is followed 6459 by the special character asterisk ('*'), together with that asterisk it shall match what zero 6460 or more consecutive occurrences of the BRE would match. For example, "[ab]*" and 6461 "[ab][ab]" are equivalent when matching the string "ab". 6462 5. When a BRE matching a single character, a subexpression, or a back-reference is followed 6463 by an interval expression of the format "\{m\}", "\{m,\}", or "\{m,n\}", together with 6464 that interval expression it shall match what repeated consecutive occurrences of the BRE 6465 would match. The values of m and n are decimal integers in the range 0 6466 m n {RE_DUP_MAX}, where m specifies the exact or minimum number of occurrences 6467 and n specifies the maximum number of occurrences. The expression "\{m\}" shall match 6468 exactly m occurrences of the preceding BRE, "\{m,\}" shall match at least m occurrences, 6469 and "\{m,n\}" shall match any number of occurrences between m and n, inclusive. 6470 For example, in the string "abababccccccd" the BRE "c\{3\}" is matched by 6471 characters '7' to '9', the BRE "\(ab\)\{4,\}" is not matched at all, and the BRE 6472 "c\{1,3\}d" is matched by characters ten to thirteen. 6473 The behavior of multiple adjacent duplication symbols ('*' and intervals) produces undefined 6474 results. 6475 A subexpression repeated by an asterisk ('*') or an interval expression shall not match a null 6476 expression unless this is the only match for the repetition or it is necessary to satisfy the exact or 6477 minimum number of occurrences for the interval expression. | Base Definitions, Issue 6 201 Basic Regular Expressions Regular Expressions 6478 9.3.7 BRE Precedence 6479 The order of precedence shall be as shown in the following table: ___________________________________________________________ 6480 _ BRE Precedence (from high to low) __________________________________________________________ 6481 Collation-related bracket symbols [==] [::] [..] 6482 Escaped characters \ 6483 Bracket expression [] 6484 Subexpressions/back-references \(\) \n 6485 Single-character-BRE duplication * \{m,n\} 6486 Concatenation 6487 _ Anchoring ^ $ __________________________________________________________ 6488 9.3.8 BRE Expression Anchoring 6489 A BRE can be limited to matching strings that begin or end a line; this is called anchoring. The 6490 circumflex and dollar sign special characters shall be considered BRE anchors in the following 6491 contexts: 6492 1. A circumflex (' ') shall be an anchor when used as the first character of an entire BRE. 6493 The implementation may treat the circumflex as an anchor when used as the first character 6494 of a subexpression. The circumflex shall anchor the expression (or optionally 6495 subexpression) to the beginning of a string; only sequences starting at the first character of 6496 a string shall be matched by the BRE. For example, the BRE " ab" matches "ab" in the 6497 string "abcdef", but fails to match in the string "cdefab". The BRE "\( ab\)" may 6498 match the former string. A portable BRE shall escape a leading circumflex in a 6499 subexpression to match a literal circumflex. 6500 2. A dollar sign ('$') shall be an anchor when used as the last character of an entire BRE. 6501 The implementation may treat a dollar sign as an anchor when used as the last character of 6502 a subexpression. The dollar sign shall anchor the expression (or optionally subexpression) 6503 to the end of the string being matched; the dollar sign can be said to match the end-of- 6504 string following the last character. 6505 3. A BRE anchored by both ' ' and '$' shall match only an entire string. For example, the 6506 BRE " abcdef$" matches strings consisting only of "abcdef". 202 Technical Standard (2000) (Draft July 28, 2000) Regular Expressions Extended Regular Expressions 6507 9.4 Extended Regular Expressions 6508 The extended regular expression (ERE) notation and construction rules shall apply to utilities 6509 defined as using extended regular expressions; any exceptions to the following rules are noted in 6510 the descriptions of the specific utilities using EREs. | 6511 9.4.1 EREs Matching a Single Character or Collating Element 6512 An ERE ordinary character, a special character preceded by a backslash, or a period shall match 6513 a single character. A bracket expression shall match a single character or a single collating 6514 element. An ERE matching a single character enclosed in parentheses shall match the same as the 6515 ERE without parentheses would have matched. 6516 9.4.2 ERE Ordinary Characters 6517 An ordinary character is an ERE that matches itself. An ordinary character is any character in the 6518 supported character set, except for the ERE special characters listed in Section 9.4.3. The 6519 interpretation of an ordinary character preceded by a backslash ('\') is undefined. 6520 9.4.3 ERE Special Characters 6521 An ERE special character has special properties in certain contexts. Outside those contexts, or 6522 when preceded by a backslash, such a character shall be an ERE that matches the special 6523 character itself. The extended regular expression special characters and the contexts in which 6524 they shall have their special meaning are as follows: 6525 . [ \ ( The period, left-bracket, backslash, and left-parenthesis shall be special except when 6526 used in a bracket expression (see Section 9.3.5 (on page 199)). Outside a bracket 6527 expression, a left-parenthesis immediately followed by a right-parenthesis produces 6528 undefined results. 6529 ) The right-parenthesis shall be special when matched with a preceding left-parenthesis, 6530 both outside a bracket expression. 6531 * + ? { The asterisk, plus-sign, question-mark, and left-brace shall be special except when used 6532 in a bracket expression (see Section 9.3.5 (on page 199)). Any of the following uses 6533 produce undefined results: 6534 * If these characters appear first in an ERE, or immediately following a vertical-line, 6535 circumflex, or left-parenthesis 6536 * If a left-brace is not part of a valid interval expression (see Section 9.4.6 (on page 6537 204)) 6538 | The vertical-line is special except when used in a bracket expression (see Section 9.3.5 6539 (on page 199)). A vertical-line appearing first or last in an ERE, or immediately 6540 following a vertical-line or a left-parenthesis, or immediately preceding a right- 6541 parenthesis, produces undefined results. 6542 ^ The circumflex shall be special when used as: 6543 * An anchor (see Section 9.4.9 (on page 205)) 6544 * The first character of a bracket expression (see Section 9.3.5 (on page 199)) 6545 $ The dollar sign shall be special when used as an anchor. Base Definitions, Issue 6 203 Extended Regular Expressions Regular Expressions 6546 9.4.4 Periods in EREs 6547 A period ('.'), when used outside a bracket expression, is an ERE that shall match any 6548 character in the supported character set except NUL. 6549 9.4.5 ERE Bracket Expression 6550 The rules for ERE Bracket Expressions are the same as for Basic Regular Expressions; see Section 6551 9.3.5 (on page 199). 6552 9.4.6 EREs Matching Multiple Characters 6553 The following rules shall be used to construct EREs matching multiple characters from EREs 6554 matching a single character: 6555 1. A concatenation of EREs shall match the concatenation of the character sequences matched 6556 by each component of the ERE. A concatenation of EREs enclosed in parentheses shall 6557 match whatever the concatenation without the parentheses matches. For example, both the 6558 ERE "cd" and the ERE "(cd)" are matched by the third and fourth character of the string 6559 "abcdefabcdef". 6560 2. When an ERE matching a single character or an ERE enclosed in parentheses is followed by 6561 the special character plus-sign ('+'), together with that plus-sign it shall match what one 6562 or more consecutive occurrences of the ERE would match. For example, the ERE 6563 "b+(bc)" matches the fourth to seventh characters in the string "acabbbcde". And, 6564 "[ab]+" and "[ab][ab]*" are equivalent. 6565 3. When an ERE matching a single character or an ERE enclosed in parentheses is followed by 6566 the special character asterisk ('*'), together with that asterisk it shall match what zero or 6567 more consecutive occurrences of the ERE would match. For example, the ERE "b*c" 6568 matches the first character in the string "cabbbcde", and the ERE "b*cd" matches the 6569 third to seventh characters in the string "cabbbcdebbbbbbcdbc". And, "[ab]*" and 6570 [ab][ab] are equivalent when matching the string "ab". 6571 4. When an ERE matching a single character or an ERE enclosed in parentheses is followed by 6572 the special character question-mark ('?'), together with that question-mark it shall match 6573 what zero or one consecutive occurrences of the ERE would match. For example, the ERE 6574 "b?c" matches the second character in the string "acabbbcde". 6575 5. When an ERE matching a single character or an ERE enclosed in parentheses is followed by 6576 an interval expression of the format "{m}", "{m,}", or "{m,n}", together with that 6577 interval expression it shall match what repeated consecutive occurrences of the ERE would 6578 match. The values of m and n are decimal integers in the range 0 m n {RE_DUP_MAX}, 6579 where m specifies the exact or minimum number of occurrences and n specifies the 6580 maximum number of occurrences. The expression "{m}" matches exactly m occurrences 6581 of the preceding ERE, "{m,}" matches at least m occurrences, and "{m,n}" matches any 6582 number of occurrences between m and n, inclusive. 6583 For example, in the string "abababccccccd" the ERE "c{3}" is matched by characters 6584 '7' to '9' and the ERE "(ab){2,}" is matched by characters one to six. 6585 The behavior of multiple adjacent duplication symbols ('+', '*', '?', and intervals) produces 6586 undefined results. 6587 An ERE matching a single character repeated by an '*', '?', or an interval expression shall not 6588 match a null expression unless this is the only match for the repetition or it is necessary to satisfy 6589 the exact or minimum number of occurrences for the interval expression. 204 Technical Standard (2000) (Draft July 28, 2000) Regular Expressions Extended Regular Expressions 6590 9.4.7 ERE Alternation 6591 Two EREs separated by the special character vertical-line ('|') shall match a string that is 6592 matched by either. For example, the ERE "a((bc)|d)" matches the string "abc" and the string 6593 "ad". Single characters, or expressions matching single characters, separated by the vertical bar 6594 and enclosed in parentheses, shall be treated as an ERE matching a single character. 6595 9.4.8 ERE Precedence 6596 The order of precedence shall be as shown in the following table: ___________________________________________________________ 6597 _ ERE Precedence (from high to low) __________________________________________________________ 6598 Collation-related bracket symbols [==] [::] [..] 6599 Escaped characters \ 6600 Bracket expression [] 6601 Grouping () 6602 Single-character-ERE duplication * + ? {m,n} 6603 Concatenation 6604 Anchoring ^ $ 6605 _ Alternation | __________________________________________________________ 6606 For example, the ERE "abba|cde" matches either the string "abba" or the string "cde" 6607 (rather than the string "abbade" or "abbcde", because concatenation has a higher order of 6608 precedence than alternation). 6609 9.4.9 ERE Expression Anchoring 6610 An ERE can be limited to matching strings that begin or end a line; this is called anchoring. The 6611 circumflex and dollar sign special characters shall be considered ERE anchors when used 6612 anywhere outside a bracket expression. This shall have the following effects: 6613 1. A circumflex (' ') outside a bracket expression shall anchor the expression or 6614 subexpression it begins to the beginning of a string; such an expression or subexpression 6615 can match only a sequence starting at the first character of a string. For example, the EREs 6616 " ab" and "( ab)" match "ab" in the string "abcdef", but fail to match in the string 6617 "cdefab", and the ERE "a b" is valid, but can never match because the 'a' prevents the 6618 expression " b" from matching starting at the first character. 6619 2. A dollar sign ('$') outside a bracket expression shall anchor the expression or 6620 subexpression it ends to the end of a string; such an expression or subexpression can 6621 match only a sequence ending at the last character of a string. For example, the EREs 6622 "ef$" and "(ef$)" match "ef" in the string "abcdef", but fail to match in the string 6623 "cdefab", and the ERE "e$f" is valid, but can never match because the 'f' prevents the 6624 expression "e$" from matching ending at the last character. Base Definitions, Issue 6 205 Regular Expression Grammar Regular Expressions 6625 9.5 Regular Expression Grammar 6626 Grammars describing the syntax of both basic and extended regular expressions are presented in 6627 this section. The grammar takes precedence over the text. See the Shell and Utilities volume of | 6628 IEEE Std. 1003.1-200x, Section 1.10, Grammar Conventions. | 6629 9.5.1 BRE/ERE Grammar Lexical Conventions 6630 The lexical conventions for regular expressions are as described in this section. 6631 Except as noted, the longest possible token or delimiter beginning at a given point is recognized. 6632 The following tokens are processed (in addition to those string constants shown in the 6633 grammar): 6634 COLL_ELEM Any single-character collating element, unless it is a META_CHAR. 6635 BACKREF Applicable only to basic regular expressions. The character string 6636 consisting of '\' followed by a single-digit numeral, '1' to '9'. 6637 DUP_COUNT Represents a numeric constant. It shall be an integer in the range 0 6638 DUP_COUNT {RE_DUP_MAX}. This token is only recognized when 6639 the context of the grammar requires it. At all other times, digits not 6640 preceded by '\' are treated as ORD_CHAR. 6641 META_CHAR One of the characters: 6642 ^ When found first in a bracket expression 6643 - When found anywhere but first (after an initial ' ', if any) or 6644 last in a bracket expression, or as the ending range point in a 6645 range expression 6646 ] When found anywhere but first (after an initial ' ', if any) in a 6647 bracket expression 6648 L_ANCHOR Applicable only to basic regular expressions. The character ' ' when it 6649 appears as the first character of a basic regular expression and when not 6650 QUOTED_CHAR. The ' ' may be recognized as an anchor elsewhere; 6651 see Section 9.3.8 (on page 202). 6652 ORD_CHAR A character, other than one of the special characters in SPEC_CHAR. 6653 QUOTED_CHAR In a BRE, one of the character sequences: 6654 \ \. \* \[ \$ \\ 6655 In an ERE, one of the character sequences: 6656 \ \. \[ \$ \( \) \| 6657 \* \+ \? \{ \\ 6658 R_ANCHOR (Applicable only to basic regular expressions.) The character '$' when it 6659 appears as the last character of a basic regular expression and when not 6660 QUOTED_CHAR. The '$' may be recognized as an anchor elsewhere; 6661 see Section 9.3.8 (on page 202). 6662 SPEC_CHAR For basic regular expressions, one of the following special characters: 6663 . Anywhere outside bracket expressions 6664 \ Anywhere outside bracket expressions 206 Technical Standard (2000) (Draft July 28, 2000) Regular Expressions Regular Expression Grammar 6665 [ Anywhere outside bracket expressions 6666 ^ When used as an anchor (see Section 9.3.8 (on page 202)) or 6667 when first in a bracket expression 6668 $ When used as an anchor 6669 * Anywhere except first in an entire RE, anywhere in a bracket 6670 expression, directly following "\(", directly following an 6671 anchoring ' ' 6672 For extended regular expressions, shall be one of the following special 6673 characters found anywhere outside bracket expressions: 6674 ^ . [ $ ( ) | 6675 * + ? { \ 6676 (The close-parenthesis shall be considered special in this context only if 6677 matched with a preceding open-parenthesis.) 6678 9.5.2 RE and Bracket Expression Grammar 6679 This section presents the grammar for basic regular expressions, including the bracket 6680 expression grammar that is common to both BREs and EREs. 6681 %token ORD_CHAR QUOTED_CHAR DUP_COUNT 6682 %token BACKREF L_ANCHOR R_ANCHOR 6683 %token Back_open_paren Back_close_paren 6684 /* '\(' '\)' */ 6685 %token Back_open_brace Back_close_brace 6686 /* '\{' '\}' */ 6687 /* The following tokens are for the Bracket Expression 6688 grammar common to both REs and EREs. */ 6689 %token COLL_ELEM META_CHAR 6690 %token Open_equal Equal_close Open_dot Dot_close Open_colon Colon_close 6691 /* '[=' '=]' '[.' '.]' '[:' ':]' */ 6692 %token class_name 6693 /* class_name is a keyword to the LC_CTYPE locale category */ 6694 /* (representing a character class) in the current locale */ 6695 /* and is only recognized between [: and :] */ 6696 %start basic_reg_exp 6697 %% 6698 /* -------------------------------------------- 6699 Basic Regular Expression 6700 -------------------------------------------- 6701 */ 6702 basic_reg_exp : RE_expression 6703 | L_ANCHOR 6704 | R_ANCHOR 6705 | L_ANCHOR R_ANCHOR 6706 | L_ANCHOR RE_expression 6707 | RE_expression R_ANCHOR Base Definitions, Issue 6 207 Regular Expression Grammar Regular Expressions 6708 | L_ANCHOR RE_expression R_ANCHOR 6709 ; 6710 RE_expression : simple_RE 6711 | RE_expression simple_RE 6712 ; 6713 simple_RE : nondupl_RE 6714 | nondupl_RE RE_dupl_symbol 6715 ; 6716 nondupl_RE : one_character_RE 6717 | Back_open_paren RE_expression Back_close_paren 6718 | BACKREF 6719 ; 6720 one_character_RE : ORD_CHAR 6721 | QUOTED_CHAR 6722 | '.' 6723 | bracket_expression 6724 ; 6725 RE_dupl_symbol : '*' 6726 | Back_open_brace DUP_COUNT Back_close_brace 6727 | Back_open_brace DUP_COUNT ',' Back_close_brace 6728 | Back_open_brace DUP_COUNT ',' DUP_COUNT Back_close_brace 6729 ; 6730 /* -------------------------------------------- 6731 Bracket Expression 6732 ------------------------------------------- 6733 */ 6734 bracket_expression : '[' matching_list ']' 6735 | '[' nonmatching_list ']' 6736 ; 6737 matching_list : bracket_list 6738 ; 6739 nonmatching_list : ' ' bracket_list 6740 ; 6741 bracket_list : follow_list 6742 | follow_list '-' 6743 ; 6744 follow_list : expression_term 6745 | follow_list expression_term 6746 ; 6747 expression_term : single_expression 6748 | range_expression 6749 ; 6750 single_expression : end_range 6751 | character_class 6752 | equivalence_class 6753 ; 6754 range_expression : start_range end_range 6755 | start_range '-' 6756 ; 6757 start_range : end_range '-' 6758 ; 6759 end_range : COLL_ELEM 208 Technical Standard (2000) (Draft July 28, 2000) Regular Expressions Regular Expression Grammar 6760 | collating_symbol 6761 ; 6762 collating_symbol : Open_dot COLL_ELEM Dot_close 6763 | Open_dot META_CHAR Dot_close 6764 ; 6765 equivalence_class : Open_equal COLL_ELEM Equal_close 6766 ; 6767 character_class : Open_colon class_name Colon_close 6768 ; 6769 The BRE grammar does not permit L_ANCHOR or R_ANCHOR inside "\(" and "\)" (which 6770 implies that ' ' and '$' are ordinary characters). This reflects the semantic limits on the 6771 application, as noted in Section 9.3.8 (on page 202). Implementations are permitted to extend the 6772 language to interpret ' ' and '$' as anchors in these locations, and as such, portable 6773 applications cannot use unescaped ' ' and '$' in positions inside "\(" and "\)" that might 6774 be interpreted as anchors. | 6775 9.5.3 ERE Grammar 6776 This section presents the grammar for extended regular expressions, excluding the bracket 6777 expression grammar. 6778 Note: The bracket expression grammar and the associated %token lines are identical 6779 between BREs and EREs. It has been omitted from the ERE section to avoid 6780 unnecessary editorial duplication. 6781 %token ORD_CHAR QUOTED_CHAR DUP_COUNT 6782 %start extended_reg_exp 6783 %% 6784 /* -------------------------------------------- 6785 Extended Regular Expression 6786 -------------------------------------------- 6787 */ 6788 extended_reg_exp : ERE_branch 6789 | extended_reg_exp '|' ERE_branch 6790 ; 6791 ERE_branch : ERE_expression 6792 | ERE_branch ERE_expression 6793 ; 6794 ERE_expression : one_character_ERE 6795 | ' ' 6796 | '$' 6797 | '(' extended_reg_exp ')' 6798 | ERE_expression ERE_dupl_symbol 6799 ; 6800 one_character_ERE : ORD_CHAR 6801 | QUOTED_CHAR 6802 | '.' 6803 | bracket_expression 6804 ; 6805 ERE_dupl_symbol : '*' 6806 | '+' 6807 | '?' 6808 | '{' DUP_COUNT '}' Base Definitions, Issue 6 209 Regular Expression Grammar Regular Expressions 6809 | '{' DUP_COUNT ',' '}' 6810 | '{' DUP_COUNT ',' DUP_COUNT '}' 6811 ; 6812 The ERE grammar does not permit several constructs that previous sections specify as having 6813 undefined results: 6814 * ORD_CHAR preceded by '\' 6815 * One or more ERE_dupl_symbols appearing first in an ERE, or immediately following '|', 6816 ' ', or '(' 6817 * '{' not part of a valid ERE_dupl_symbol 6818 * '|' appearing first or last in an ERE, or immediately following '|' or '(', or immediately 6819 preceding ')' 6820 Implementations are permitted to extend the language to allow these. Portable applications | 6821 cannot use such constructs. 210 Technical Standard (2000) (Draft July 28, 2000) Chapter 10 Directory Structure and Devices 6822 6823 10.1 Directory Structure and Files 6824 The following directories shall exist on conforming systems and portable applications shall 6825 make use of them only as described. Portable applications shall not assume the ability to create 6826 files in any of these directories, unless specified below. 6827 / The root directory. 6828 /dev Contains /dev/console, /dev/null, and /dev/tty, described below. | 6829 The following directory shall exist on conforming systems and shall be used as described. 6830 /tmp A directory made available for programs that need a place to create temporary 6831 files. Applications are allowed to create files in this directory, but cannot assume 6832 that such files are preserved between invocations of the application. | 6833 The following files shall exist on conforming systems and shall be both readable and writable. 6834 /dev/null An infinite data source and data sink. Data written to /dev/null shall be discarded. 6835 Reads from /dev/null shall always return end-of-file (EOF). 6836 /dev/tty In each process, a synonym for the controlling terminal associated with the process 6837 group of that process, if any. It is useful for programs or shell procedures that wish 6838 to be sure of writing messages to or reading data from the terminal no matter how 6839 output has been redirected. It can also be used for programs that demand the name 6840 of a file for output, when typed output is desired and it is tiresome to find out 6841 what terminal is currently in use. 6842 The following file shall exist on conforming systems and need not be readable or writable: | 6843 /dev/console The /dev/console file is a generic name given to the system console. It is usually 6844 linked to a particular machine-dependent special file. It shall provide a basic I/O 6845 interface to the system console. | 6846 10.2 Output Devices and Terminal Types 6847 The utilities in the Shell and Utilities volume of IEEE Std. 1003.1-200x historically have been | 6848 implemented on a wide range of terminal types, but a conforming implementation need not | 6849 support all features of all utilities on every conceivable terminal. IEEE Std. 1003.1-200x states 6850 which features are optional for certain classes of terminals in the individual utility description 6851 sections. The implementation shall document which terminal types it supports and which of 6852 these features and utilities are not supported by each terminal. 6853 When a feature or utility is not supported on a specific terminal type, as allowed by 6854 IEEE Std. 1003.1-200x, and the implementation considers such a condition to be an error 6855 preventing use of the feature or utility, the implementation shall indicate such conditions 6856 through diagnostic messages or exit status values or both (as appropriate to the specific utility 6857 description) that inform the user that the terminal type lacks the appropriate capability. 6858 IEEE Std. 1003.1-200x uses a notational convention based on historical practice that identifies 6859 some of the control characters defined in Section 7.3.1 (on page 147) in a manner easily Base Definitions, Issue 6 211 Output Devices and Terminal Types Directory Structure and Devices 6860 remembered by users on many terminals. The correspondence between this ``-char'' 6861 notation and the actual control characters is shown in the following table. When 6862 IEEE Std. 1003.1-200x refers to a character by its - name, it is referring to the actual | 6863 control character shown in the Value column of the table, which is not necessarily the exact | 6864 control key sequence on all terminals. Some terminals have keyboards that do not allow the | 6865 direct transmission of all the non-alphanumeric characters shown. In such cases, the system | 6866 documentation shall describe which data sequences transmitted by the terminal are interpreted | 6867 by the system as representing the special characters. | 6868 Table 10-1 Control Character Names ____________________________________________________________________________________ 6869 _ Name Value Symbolic Name Name Value Symbolic Name ___________________________________________________________________________________ 6870 -A -Q 6871 -B -R 6872 -C -S 6873 -D -T 6874 -E -U 6875 -F -V 6876 -G -W 6877 -H -X 6878 -I -Y 6879 -J -Z 6880 -K -[ 6881 -L -\ 6882 -M -] 6883 -N - 6884 -O -_ 6885 _ -P -? ___________________________________________________________________________________ 6886 Note: The notation uses uppercase letters for arbitrary editorial reasons. There is no 6887 implication that the keystrokes represent control-shift-letter sequences. | 212 Technical Standard (2000) (Draft July 28, 2000) Chapter 11 General Terminal Interface 6888 6889 This chapter describes a general terminal interface that shall be provided. It shall be supported 6890 on any asynchronous communications ports if the implementation provides them. It is | 6891 implementation-defined whether it supports network connections or synchronous ports, or | 6892 both. 6893 11.1 Interface Characteristics 6894 11.1.1 Opening a Terminal Device File 6895 When a terminal device file is opened, it normally causes the thread to wait until a connection is 6896 established. In practice, application programs seldom open these files; they are opened by 6897 special programs and become an application's standard input, output, and error files. 6898 As described in open( ), opening a terminal device file with the O_NONBLOCK flag clear shall 6899 cause the thread to block until the terminal device is ready and available. If CLOCAL mode is 6900 not set, this means blocking until a connection is established. If CLOCAL mode is set in the 6901 terminal, or the O_NONBLOCK flag is specified in the open( ), the open( ) function shall return a 6902 file descriptor without waiting for a connection to be established. 6903 11.1.2 Process Groups 6904 A terminal may have a foreground process group associated with it. This foreground process 6905 group plays a special role in handling signal-generating input characters, as discussed in Section 6906 11.1.9 (on page 217). 6907 A command interpreter process supporting job control can allocate the terminal to different jobs, 6908 or process groups, by placing related processes in a single process group and associating this 6909 process group with the terminal. A terminal's foreground process group may be set or examined 6910 by a process, assuming the permission requirements are met; see tcgetpgrp( ) and tcsetpgrp( ). The 6911 terminal interface aids in this allocation by restricting access to the terminal by processes that are 6912 not in the current process group; see Section 11.1.4 (on page 214). 6913 When there is no longer any process whose process ID or process group ID matches the process 6914 group ID of the foreground process group, the terminal shall have no foreground process group. 6915 It is unspecified whether the terminal has a foreground process group when there is a process 6916 whose process ID matches the foreground process ID, but whose process group ID does not. No 6917 actions defined in IEEE Std. 1003.1-200x, other than allocation of a controlling terminal or a 6918 successful call to tcsetpgrp( ), cause a process group to become the foreground process group of 6919 the terminal. Base Definitions, Issue 6 213 Interface Characteristics General Terminal Interface 6920 11.1.3 The Controlling Terminal 6921 A terminal may belong to a process as its controlling terminal. Each process of a session that has 6922 a controlling terminal has the same controlling terminal. A terminal may be the controlling 6923 terminal for at most one session. The controlling terminal for a session is allocated by the session | 6924 leader in an implementation-defined manner. If a session leader has no controlling terminal, and | 6925 opens a terminal device file that is not already associated with a session without using the 6926 O_NOCTTY option (see open( )), it is implementation-defined whether the terminal becomes the | 6927 controlling terminal of the session leader. If a process which is not a session leader opens a 6928 terminal file, or the O_NOCTTY option is used on open( ), then that terminal shall not become 6929 the controlling terminal of the calling process. When a controlling terminal becomes associated 6930 with a session, its foreground process group shall be set to the process group of the session 6931 leader. 6932 The controlling terminal is inherited by a child process during a fork( ) function call. A process 6933 relinquishes its controlling terminal when it creates a new session with the setsid( ) function; 6934 other processes remaining in the old session that had this terminal as their controlling terminal 6935 continue to have it. Upon the close of the last file descriptor in the system (whether or not it is in 6936 the current session) associated with the controlling terminal, it is unspecified whether all 6937 processes that had that terminal as their controlling terminal cease to have any controlling 6938 terminal. Whether and how a session leader can reacquire a controlling terminal after the 6939 controlling terminal has been relinquished in this fashion is unspecified. A process does not 6940 relinquish its controlling terminal simply by closing all of its file descriptors associated with the 6941 controlling terminal if other processes continue to have it open. 6942 When a controlling process terminates, the controlling terminal is dissociated from the current 6943 session, allowing it to be acquired by a new session leader. Subsequent access to the terminal by 6944 other processes in the earlier session may be denied, with attempts to access the terminal treated 6945 as if a modem disconnect had been sensed. 6946 11.1.4 Terminal Access Control 6947 If a process is in the foreground process group of its controlling terminal, read operations shall 6948 be allowed, as described in Section 11.1.5 (on page 215). Any attempts by a process in a 6949 background process group to read from its controlling terminal cause its process group to be 6950 sent a SIGTTIN signal unless one of the following special cases applies: if the reading process is 6951 ignoring or blocking the SIGTTIN signal, or if the process group of the reading process is 6952 orphaned, the read( ) returns -1, with errno set to [EIO] and no signal is sent. The default action of 6953 the SIGTTIN signal is to stop the process to which it is sent. See . 6954 If a process is in the foreground process group of its controlling terminal, write operations shall 6955 be allowed as described in Section 11.1.8 (on page 217). Attempts by a process in a background 6956 process group to write to its controlling terminal shall cause the process group to be sent a 6957 SIGTTOU signal unless one of the following special cases applies: if TOSTOP is not set, or if 6958 TOSTOP is set and the process is ignoring or blocking the SIGTTOU signal, the process is 6959 allowed to write to the terminal and the SIGTTOU signal is not sent. If TOSTOP is set, and the 6960 process group of the writing process is orphaned, and the writing process is not ignoring or 6961 blocking the SIGTTOU signal, the write( ) returns -1, with errno set to [EIO] and no signal is sent. 6962 Certain calls that set terminal parameters are treated in the same fashion as write( ), except that 6963 TOSTOP is ignored; that is, the effect is identical to that of terminal writes when TOSTOP is set 6964 (see Section 11.2.5 (on page 223), tcdrain( ), tcflow( ), tcflush( ), tcsendbreak( ), tcsetattr( ), and | 6965 tcsetpgrp( )). | 214 Technical Standard (2000) (Draft July 28, 2000) General Terminal Interface Interface Characteristics 6966 11.1.5 Input Processing and Reading Data 6967 A terminal device associated with a terminal device file may operate in full-duplex mode, so that 6968 data may arrive even while output is occurring. Each terminal device file has an input queue, 6969 associated with it, into which incoming data is stored by the system before being read by a 6970 process. The system may impose a limit, {MAX_INPUT}, on the number of bytes that may be 6971 stored in the input queue. The behavior of the system when this limit is exceeded is | 6972 implementation-defined. | 6973 Two general kinds of input processing are available, determined by whether the terminal device 6974 file is in canonical mode or non-canonical mode. These modes are described in Section 11.1.6 and 6975 Section 11.1.7 (on page 216). Additionally, input characters are processed according to the 6976 c_iflag (see Section 11.2.2 (on page 219)) and c_lflag (see Section 11.2.5 (on page 223)) fields. 6977 Such processing can include echoing, which in general means transmitting input characters 6978 immediately back to the terminal when they are received from the terminal. This is useful for 6979 terminals that can operate in full-duplex mode. 6980 The manner in which data is provided to a process reading from a terminal device file is 6981 dependent on whether the terminal file is in canonical or non-canonical mode, and on whether 6982 or not the O_NONBLOCK flag is set by open( ) or fcntl( ). 6983 If the O_NONBLOCK flag is clear, then the read request shall be blocked until data is available 6984 or a signal has been received. If the O_NONBLOCK flag is set, then the read request shall be 6985 completed, without blocking, in one of three ways: 6986 1. If there is enough data available to satisfy the entire request, the read( ) shall complete 6987 successfully and shall return the number of bytes read. 6988 2. If there is not enough data available to satisfy the entire request, the read( ) shall complete 6989 successfully, having read as much data as possible, and shall return the number of bytes it 6990 was able to read. 6991 3. If there is no data available, the read( ) shall return -1, with errno set to [EAGAIN]. 6992 When data is available depends on whether the input processing mode is canonical or non- 6993 canonical. The following sections, Section 11.1.6 and Section 11.1.7 (on page 216), describe each 6994 of these input processing modes. 6995 11.1.6 Canonical Mode Input Processing 6996 In canonical mode input processing, terminal input is processed in units of lines. A line is 6997 delimited by a newline character (NL), an end-of-file character (EOF), or an end-of-line (EOL) 6998 character. See Section 11.1.9 (on page 217) for more information on EOF and EOL. This means 6999 that a read request shall not return until an entire line has been typed or a signal has been 7000 received. Also, no matter how many bytes are requested in the read( ) call, at most one line shall 7001 be returned. It is not, however, necessary to read a whole line at once; any number of bytes, even 7002 one, may be requested in a read( ) without losing information. 7003 If {MAX_CANON} is defined for this terminal device, it is a limit on the number of bytes in a 7004 line. The behavior of the system when this limit is exceeded is implementation-defined. If | 7005 {MAX_CANON} is not defined, there is no such limit; see pathconf( ). 7006 Erase and kill processing occur when either of two special characters, the ERASE and KILL 7007 characters (see Section 11.1.9 (on page 217)), is received. This processing affects data in the input 7008 queue that has not yet been delimited by a newline (NL), EOF, or EOL character. This un- 7009 delimited data makes up the current line. The ERASE character deletes the last character in the 7010 current line, if there is one. The KILL character deletes all data in the current line, if there are any. 7011 The ERASE and KILL characters have no effect if there is no data in the current line. The ERASE Base Definitions, Issue 6 215 Interface Characteristics General Terminal Interface 7012 and KILL characters themselves are not placed in the input queue. 7013 11.1.7 Non-Canonical Mode Input Processing 7014 In non-canonical mode input processing, input bytes are not assembled into lines, and erase and 7015 kill processing do not occur. The values of the MIN and TIME members of the c_cc array are 7016 used to determine how to process the bytes received. The IEEE Std. 1003.1-200x does not specify 7017 whether the setting of O_NONBLOCK takes precedence over MIN or TIME settings. Therefore, 7018 if O_NONBLOCK is set, read( ) may return immediately, regardless of the setting of MIN or 7019 TIME. Also, if no data is available, read( ) may either return 0, or return -1 with errno set to 7020 [EAGAIN]. 7021 MIN represents the minimum number of bytes that should be received when the read( ) function 7022 returns successfully. TIME is a timer of 0.1 second granularity that is used to time out bursty and 7023 short-term data transmissions. If MIN is greater than {MAX_INPUT}, the response to the request 7024 is undefined. The four possible values for MIN and TIME and their interactions are described 7025 below. 7026 Case A: MIN>0, TIME>0 7027 In case A, TIME serves as an inter-byte timer and is activated after the first byte is received. Since | 7028 it is an inter-byte timer, it is reset after a byte is received. The interaction between MIN and 7029 TIME is as follows. As soon as one byte is received, the inter-byte timer is started. If MIN bytes 7030 are received before the inter-byte timer expires (remember that the timer is reset upon receipt of 7031 each byte), the read is satisfied. If the timer expires before MIN bytes are received, the characters 7032 received to that point are returned to the user. Note that if TIME expires at least one byte is 7033 returned because the timer would not have been enabled unless a byte was received. In this case 7034 (MIN>0, TIME>0) the read shall block until the MIN and TIME mechanisms are activated by the 7035 receipt of the first byte, or a signal is received. If the data is in the buffer at the time of the read( ), 7036 the result shall be as if the data has been received immediately after the read( ). 7037 Case B: MIN>0, TIME=0 7038 In case B, since the value of TIME is zero, the timer plays no role and only MIN is significant. A | 7039 pending read is not satisfied until MIN bytes are received (that is, the pending read shall block | 7040 until MIN bytes are received), or a signal is received. A program that uses case B to read record- | 7041 based terminal I/O may block indefinitely in the read operation. | 7042 Case C: MIN=0, TIME>0 7043 In case C, since MIN=0, TIME no longer represents an inter-byte timer. It now serves as a read | 7044 timer that is activated as soon as the read( ) function is processed. A read is satisfied as soon as a | 7045 single byte is received or the read timer expires. Note that in case C if the timer expires, no bytes | 7046 are returned. If the timer does not expire, the only way the read can be satisfied is if a byte is | 7047 received. If bytes are not received, the read shall not block indefinitely waiting for a byte; if no | 7048 byte is received within TIME*0.1 seconds after the read is initiated, the read( ) returns a value of | 7049 zero, having read no data. If the data is in the buffer at the time of the read( ), the timer shall be 7050 started as if the data has been received immediately after the read( ). 216 Technical Standard (2000) (Draft July 28, 2000) General Terminal Interface Interface Characteristics 7051 Case D: MIN=0, TIME=0 7052 The minimum of either the number of bytes requested or the number of bytes currently available 7053 shall be returned without waiting for more bytes to be input. If no characters are available, read( ) 7054 shall return a value of zero, having read no data. 7055 11.1.8 Writing Data and Output Processing 7056 When a process writes one or more bytes to a terminal device file, they are processed according 7057 to the c_oflag field (see Section 11.2.3 (on page 220)). The implementation may provide a 7058 buffering mechanism; as such, when a call to write( ) completes, all of the bytes written have 7059 been scheduled for transmission to the device, but the transmission has not necessarily 7060 completed. See write( ) for the effects of O_NONBLOCK on write( ). 7061 11.1.9 Special Characters 7062 Certain characters have special functions on input or output or both. These functions are 7063 summarized as follows: 7064 INTR Special character on input, which is recognized if the ISIG flag is set. Generates a 7065 SIGINT signal which is sent to all processes in the foreground process group for which 7066 the terminal is the controlling terminal. If ISIG is set, the INTR character is discarded 7067 when processed. 7068 QUIT Special character on input, which is recognized if the ISIG flag is set. Generates a 7069 SIGQUIT signal which is sent to all processes in the foreground process group for 7070 which the terminal is the controlling terminal. If ISIG is set, the QUIT character is 7071 discarded when processed. 7072 ERASE Special character on input, which is recognized if the ICANON flag is set. Erases the 7073 last character in the current line; see Section 11.1.6 (on page 215). It shall not erase 7074 beyond the start of a line, as delimited by an NL, EOF, or EOL character. If ICANON is 7075 set, the ERASE character is discarded when processed. 7076 KILL Special character on input, which is recognized if the ICANON flag is set. Deletes the 7077 entire line, as delimited by an NL, EOF, or EOL character. If ICANON is set, the KILL 7078 character is discarded when processed. 7079 EOF Special character on input, which is recognized if the ICANON flag is set. When 7080 received, all the bytes waiting to be read are immediately passed to the process without 7081 waiting for a newline, and the EOF is discarded. Thus, if there are no bytes waiting 7082 (that is, the EOF occurred at the beginning of a line), a byte count of zero shall be 7083 returned from the read( ), representing an end-of-file indication. If ICANON is set, the 7084 EOF character is discarded when processed. 7085 NL Special character on input, which is recognized if the ICANON flag is set. It is the line 7086 delimiter newline. It cannot be changed. 7087 EOL Special character on input, which is recognized if the ICANON flag is set. It is an 7088 additional line delimiter, like NL. 7089 SUSP If the ISIG flag is set, receipt of the SUSP character causes a SIGTSTP signal to be sent 7090 to all processes in the foreground process group for which the terminal is the 7091 controlling terminal, and the SUSP character is discarded when processed. 7092 STOP Special character on both input and output, which is recognized if the IXON (output 7093 control) or IXOFF (input control) flag is set. Can be used to suspend output 7094 temporarily. It is useful with CRT terminals to prevent output from disappearing Base Definitions, Issue 6 217 Interface Characteristics General Terminal Interface 7095 before it can be read. If IXON is set, the STOP character is discarded when processed. 7096 START Special character on both input and output, which is recognized if the IXON (output 7097 control) or IXOFF (input control) flag is set. Can be used to resume output that has 7098 been suspended by a STOP character. If IXON is set, the START character is discarded 7099 when processed. 7100 CR Special character on input, which is recognized if the ICANON flag is set; it is the 7101 carriage-return character. When ICANON and ICRNL are set and IGNCR is not set, 7102 this character is translated into an NL, and has the same effect as an NL character. 7103 The NL and CR characters cannot be changed. It is implementation-defined whether the START | 7104 and STOP characters can be changed. The values for INTR, QUIT, ERASE, KILL, EOF, EOL, and | 7105 SUSP shall be changeable to suit individual tastes. Special character functions associated with 7106 changeable special control characters can be disabled individually. 7107 If two or more special characters have the same value, the function performed when that 7108 character is received is undefined. 7109 A special character is recognized not only by its value, but also by its context; for example, an 7110 implementation may support multi-byte sequences that have a meaning different from the 7111 meaning of the bytes when considered individually. Implementations may also support | 7112 additional single-byte functions. These implementation-defined multi-byte or single-byte | 7113 functions are recognized only if the IEXTEN flag is set; otherwise, data is received without 7114 interpretation, except as required to recognize the special characters defined in this section. 7115 XSI If IEXTEN is set, the ERASE, KILL, and EOF characters can be escaped by a preceding '\' 7116 character, in which case no special function occurs. 7117 11.1.10 Modem Disconnect 7118 If a modem disconnect is detected by the terminal interface for a controlling terminal, and if 7119 CLOCAL is not set in the c_cflag field for the terminal (see Section 11.2.4 (on page 222)), the 7120 SIGHUP signal is sent to the controlling process for which the terminal is the controlling 7121 terminal. Unless other arrangements have been made, this causes the controlling process to 7122 terminate (see exit( )). Any subsequent read from the terminal device shall return the value of 7123 zero, indicating end-of-file; see read( ). Thus, processes that read a terminal file and test for end- 7124 of-file can terminate appropriately after a disconnect. If the EIO condition as specified in read( ) 7125 also exists, it is unspecified whether on EOF condition or the [EIO] is returned. Any subsequent 7126 write( ) to the terminal device returns -1, with errno set to [EIO], until the device is closed. 7127 11.1.11 Closing a Terminal Device File 7128 The last process to close a terminal device file shall cause any output to be sent to the device and 7129 any input to be discarded. If HUPCL is set in the control modes and the communications port 7130 supports a disconnect function, the terminal device shall perform a disconnect. | 218 Technical Standard (2000) (Draft July 28, 2000) General Terminal Interface Parameters that Can be Set 7131 11.2 Parameters that Can be Set 7132 11.2.1 The termios Structure 7133 Routines that need to control certain terminal I/O characteristics shall do so by using the 7134 termios structure as defined in the header. The members of this structure include 7135 (but are not limited to): _________________________________________________ 7136 Member Array Member 7137 _ Type Size Name Description ________________________________________________ 7138 tcflag_t c_iflag Input modes. 7139 tcflag_t c_oflag Output modes. 7140 tcflag_t c_cflag Control modes. 7141 tcflag_t c_lflag Local modes. 7142 _ cc_t NCCS c_cc[ ] Control characters. ________________________________________________ 7143 The types tcflag_t and cc_t are defined in the header. They shall be unsigned | 7144 integer types. | 7145 11.2.2 Input Modes 7146 Values of the c_iflag field describe the basic terminal input control, and are composed of the 7147 bitwise-inclusive OR of the masks shown, which shall be bitwise-distinct. The mask name 7148 symbols in this table are defined in : 7149 ___________________________________________________ 7150 _ Mask Name Description __________________________________________________ 7151 BRKINT Signal interrupt on break. 7152 ICRNL Map CR to NL on input. 7153 IGNBRK Ignore break condition. 7154 IGNCR Ignore CR. 7155 IGNPAR Ignore characters with parity errors. 7156 INLCR Map NL to CR on input. 7157 INPCK Enable input parity check. 7158 ISTRIP Strip character. 7159 XSI IXANY Enable any character to restart output. 7160 IXOFF Enable start/stop input control. 7161 IXON Enable start/stop output control. 7162 _ PARMRK Mark parity errors. __________________________________________________ 7163 In the context of asynchronous serial data transmission, a break condition is defined as a 7164 sequence of zero-valued bits that continues for more than the time to send one byte. The entire 7165 sequence of zero-valued bits is interpreted as a single break condition, even if it continues for a 7166 time equivalent to more than one byte. In contexts other than asynchronous serial data 7167 transmission, the definition of a break condition is implementation-defined. | 7168 If IGNBRK is set, a break condition detected on input is ignored; that is, not put on the input 7169 queue and therefore not read by any process. If IGNBRK is not set and BRKINT is set, the break 7170 condition shall flush the input and output queues, and if the terminal is the controlling terminal 7171 of a foreground process group, the break condition shall generate a single SIGINT signal to that 7172 foreground process group. If neither IGNBRK nor BRKINT is set, a break condition is read as a 7173 single 0x00, or if PARMRK is set, as 0xff 0x00 0x00. 7174 If IGNPAR is set, a byte with a framing or parity error (other than break) is ignored. Base Definitions, Issue 6 219 Parameters that Can be Set General Terminal Interface 7175 If PARMRK is set, and IGNPAR is not set, a byte with a framing or parity error (other than 7176 break) is given to the application as the three-byte sequence 0xff 0x00 X, where 0xff 0x00 is a 7177 two-byte flag preceding each sequence and X is the data of the byte received in error. To avoid 7178 ambiguity in this case, if ISTRIP is not set, a valid byte of 0xff is given to the application as 0xff 7179 0xff. If neither PARMRK nor IGNPAR is set, a framing or parity error (other than break) is given 7180 to the application as a single byte 0x00. 7181 If INPCK is set, input parity checking is enabled. If INPCK is not set, input parity checking is 7182 disabled, allowing output parity generation without input parity errors. Note that whether input 7183 parity checking is enabled or disabled is independent of whether parity detection is enabled or 7184 disabled (see Section 11.2.4 (on page 222)). If parity detection is enabled but input parity 7185 checking is disabled, the hardware to which the terminal is connected shall recognize the parity 7186 bit, but the terminal special file shall not check whether or not this bit is correctly set. 7187 If ISTRIP is set, valid input bytes are first stripped to seven bits; otherwise, all eight bits are 7188 processed. 7189 If INLCR is set, a received NL character is translated into a CR character. If IGNCR is set, a 7190 received CR character is ignored (not read). If IGNCR is not set and ICRNL is set, a received CR 7191 character is translated into an NL character. 7192 XSI If IXANY is set, any input character shall restart output that has been suspended. 7193 If IXON is set, start/stop output control is enabled. A received STOP character shall suspend 7194 output and a received START character shall restart output. When IXON is set, START and 7195 STOP characters are not read, but merely perform flow control functions. When IXON is not set, 7196 the START and STOP characters are read. 7197 If IXOFF is set, start/stop input control is enabled. The system shall transmit STOP characters, 7198 which are intended to cause the terminal device to stop transmitting data, as needed to prevent 7199 the input queue from overflowing and causing implementation-defined behavior, and shall | 7200 transmit START characters, which are intended to cause the terminal device to resume 7201 transmitting data, as soon as the device can continue transmitting data without risk of 7202 overflowing the input queue. The precise conditions under which STOP and START characters 7203 are transmitted are implementation-defined. | 7204 The initial input control value after open( ) is implementation-defined. | 7205 11.2.3 Output Modes 7206 The c_oflag field specifies the terminal interface's treatment of output, and is composed of the 7207 bitwise-inclusive OR of the masks shown, which shall be bitwise-distinct. The mask name 7208 symbols in this table are defined in : 220 Technical Standard (2000) (Draft July 28, 2000) General Terminal Interface Parameters that Can be Set 7209 ______________________________________________________________________________________ 7210 _ Mask Name Description _____________________________________________________________________________________ 7211 OPOST Perform output processing. 7212 XSI ONLCR Map NL to CR-NL on output. 7213 OCRNL Map CR to NL on output. 7214 ONOCR No CR output at column 0. 7215 ONLRET NL performs CR function. 7216 OFILL Use fill characters for delay. 7217 OFDEL Fill is DEL, else NUL. 7218 NLDLY Select newline delays: 7219 NL0 Newline character type 0. 7220 NL1 Newline character type 1. 7221 CRDLY Select carriage-return delays: 7222 CR0 Carriage-return delay type 0. 7223 CR1 Carriage-return delay type 1. 7224 CR2 Carriage-return delay type 2. 7225 CR3 Carriage-return delay type 3. 7226 TABDLY Select horizontal-tab delays: 7227 TAB0 Horizontal-tab delay type 0. 7228 TAB1 Horizontal-tab delay type 1. 7229 TAB2 Horizontal-tab delay type 2. 7230 TAB3 Expand tabs to spaces. 7231 BSDLY Select backspace delays: 7232 BS0 Backspace-delay type 0. 7233 BS1 Backspace-delay type 1. 7234 VTDLY Select vertical-tab delays: 7235 VT0 Vertical-tab delay type 0. 7236 VT1 Vertical-tab delay type 1. 7237 FFDLY Select form-feed delays: 7238 FF0 Form-feed delay type 0. 7239 _ FF1 Form-feed delay type 1. _____________________________________________________________________________________ 7240 If OPOST is set, output data is post-processed as described below, so that lines of text are 7241 modified to appear appropriately on the terminal device; otherwise, characters are transmitted 7242 without change. 7243 XSI If ONLCR is set, the NL character shall be transmitted as the CR-NL character pair. If OCRNL is 7244 set, the CR character shall be transmitted as the NL character. If ONOCR is set, no CR character 7245 shall be transmitted when at column 0 (first position). If ONLRET is set, the NL character is 7246 assumed to do the carriage-return function; the column pointer shall be set to 0 and the delays 7247 specified for CR shall be used. Otherwise, the NL character is assumed to do just the line-feed 7248 function; the column pointer remains unchanged. The column pointer shall also be set to 0 if the 7249 CR character is actually transmitted. 7250 The delay bits specify how long transmission stops to allow for mechanical or other movement 7251 when certain characters are sent to the terminal. In all cases a value of 0 indicates no delay. If 7252 OFILL is set, fill characters are transmitted for delay instead of a timed delay. This is useful for 7253 high baud rate terminals which need only a minimal delay. If OFDEL is set, the fill character is 7254 DEL; otherwise, NUL. 7255 If a form-feed or vertical-tab delay is specified, it lasts for about 2 seconds. 7256 New-line delay lasts about 0.10 seconds. If ONLRET is set, the carriage-return delays are used 7257 instead of the newline delays. If OFILL is set, two fill characters are transmitted. Base Definitions, Issue 6 221 Parameters that Can be Set General Terminal Interface 7258 Carriage-return delay type 1 is dependent on the current column position, type 2 is about 0.10 7259 seconds, and type 3 is about 0.15 seconds. If OFILL is set, delay type 1 transmits two fill 7260 characters, and type 2, four fill characters. 7261 Horizontal-tab delay type 1 is dependent on the current column position. Type 2 is about 0.10 7262 seconds. Type 3 specifies that tabs shall be expanded into spaces. If OFILL is set, two fill 7263 characters are transmitted for any delay. 7264 Backspace delay lasts about 0.05 seconds. If OFILL is set, one fill character is transmitted. 7265 The actual delays depend on line speed and system load. 7266 The initial output control value after open( ) is implementation-defined. | 7267 11.2.4 Control Modes 7268 The c_cflag field describes the hardware control of the terminal, and is composed of the 7269 bitwise-inclusive OR of the masks shown, which shall be bitwise-distinct. The mask name 7270 symbols in this table are defined in ; not all values specified are required to be 7271 supported by the underlying hardware: ___________________________________________________________ 7272 _ Mask Name Description __________________________________________________________ 7273 CLOCAL Ignore modem status lines. 7274 CREAD Enable receiver. 7275 CSIZE Number of bits transmitted or received per byte: 7276 CS5 5 bits 7277 CS6 6 bits 7278 CS7 7 bits 7279 CS8 8 bits. 7280 CSTOPB Send two stop bits, else one. 7281 HUPCL Hang up on last close. 7282 PARENB Parity enable. 7283 _ PARODD Odd parity, else even. __________________________________________________________ 7284 In addition, the input and output baud rates are stored in the termios structure. The following 7285 values are supported:________________________________________________ 7286 _ Name Description Name Description _______________________________________________ 7287 B0 Hang up B600 600 baud 7288 B50 50 baud B1200 1200 baud 7289 B75 75 baud B1800 1800 baud 7290 B110 110 baud B2400 2400 baud 7291 B134 134.5 baud B4800 4800 baud 7292 B150 150 baud B9600 9600 baud 7293 B200 200 baud B19200 19200 baud 7294 _ B300 300 baud B38400 38400 baud _______________________________________________ 7295 The following functions are provided for getting and setting the values of the input and output 7296 baud rates in the termios structure: cfgetispeed( ), cfgetospeed( ), cfsetispeed( ), and cfsetospeed( ). 7297 The effects on the terminal device do not become effective and not all errors are detected until 7298 the tcsetattr( ) function is successfully called. 7299 The CSIZE bits specify the number of transmitted or received bits per byte. If ISTRIP is not set, 7300 the value of all the other bits is unspecified. If ISTRIP is set, the value of all but the 7 low-order 7301 bits is zero, but the value of any other bits beyond CSIZE is unspecified when read. CSIZE does 7302 not include the parity bit, if any. If CSTOPB is set, two stop bits are used; otherwise, one stop 222 Technical Standard (2000) (Draft July 28, 2000) General Terminal Interface Parameters that Can be Set 7303 bit. For example, at 110 baud, two stop bits are normally used. 7304 If CREAD is set, the receiver is enabled; otherwise, no characters shall be received. 7305 If PARENB is set, parity generation and detection is enabled and a parity bit is added to each 7306 byte. If parity is enabled, PARODD specifies odd parity if set; otherwise, even parity is used. 7307 If HUPCL is set, the modem control lines for the port are lowered when the last process with the 7308 port open closes the port or the process terminates. The modem connection shall be broken. 7309 If CLOCAL is set, a connection does not depend on the state of the modem status lines. If 7310 CLOCAL is clear, the modem status lines shall be monitored. 7311 Under normal circumstances, a call to the open( ) function shall wait for the modem connection 7312 to complete. However, if the O_NONBLOCK flag is set (see open( )) or if CLOCAL has been set, 7313 the open( ) function shall return immediately without waiting for the connection. 7314 If the object for which the control modes are set is not an asynchronous serial connection, some 7315 of the modes may be ignored; for example, if an attempt is made to set the baud rate on a 7316 network connection to a terminal on another host, the baud rate may or may not be set on the 7317 connection between that terminal and the machine to which it is directly connected. 7318 The initial hardware control value after open( ) is implementation-defined. | 7319 11.2.5 Local Modes 7320 The c_lflag field of the argument structure is used to control various functions. It is composed 7321 of the bitwise-inclusive OR of the masks shown, which shall be bitwise-distinct. The mask name 7322 symbols in this table are defined in ; not all values specified are required to be 7323 supported by the underlying hardware: 7324 _______________________________________________________________ 7325 _ Mask Name Description ______________________________________________________________ 7326 ECHO Enable echo. 7327 ECHOE Echo ERASE as an error correcting backspace. 7328 ECHOK Echo KILL. 7329 ECHONL Echo . 7330 ICANON Canonical input (erase and kill processing). 7331 IEXTEN Enable extended (implementation-defined) functions. 7332 ISIG Enable signals. 7333 NOFLSH Disable flush after interrupt, quit or suspend. 7334 _ TOSTOP Send SIGTTOU for background output. ______________________________________________________________ 7335 If ECHO is set, input characters are echoed back to the terminal. If ECHO is clear, input 7336 characters are not echoed. 7337 If ECHOE and ICANON are set, the ERASE character shall cause the terminal to erase, if 7338 possible, the last character in the current line from the display. If there were no character to 7339 erase, an implementation might echo an indication that this was the case, or do nothing. 7340 If ECHOK and ICANON are set, the KILL character shall either cause the terminal to erase the 7341 line from the display or shall echoe the newline character after the KILL character. 7342 If ECHONL and ICANON are set, the newline character shall be echoed even if ECHO is not set. 7343 If ICANON is set, canonical processing is enabled. This enables the erase and kill edit functions, 7344 and the assembly of input characters into lines delimited by NL, EOF, and EOL, as described in 7345 Section 11.1.6 (on page 215). Base Definitions, Issue 6 223 Parameters that Can be Set General Terminal Interface 7346 If ICANON is not set, read requests are satisfied directly from the input queue. A read shall not 7347 be satisfied until at least MIN bytes have been received or the timeout value TIME expired 7348 between bytes. The time value represents tenths of a second. See Section 11.1.7 (on page 216) for 7349 more details. 7350 If IEXTEN is set, implementation-defined functions are recognized from the input data. It is | 7351 implementation-defined how IEXTEN being set interacts with ICANON, ISIG, IXON, or IXOFF. | 7352 If IEXTEN is not set, implementation-defined functions shall not be recognized and the | 7353 corresponding input characters are processed as described for ICANON, ISIG, IXON, and 7354 IXOFF. 7355 If ISIG is set, each input character is checked against the special control characters INTR, QUIT, 7356 and SUSP. If an input character matches one of these control characters, the function associated 7357 with that character is performed. If ISIG is not set, no checking is done. Thus these special input 7358 functions are possible only if ISIG is set. 7359 If NOFLSH is set, the normal flush of the input and output queues associated with the INTR, 7360 QUIT, and SUSP characters shall not be done. 7361 If TOSTOP is set, the signal SIGTTOU is sent to the process group of a process that tries to write 7362 to its controlling terminal if it is not in the foreground process group for that terminal. This 7363 signal, by default, stops the members of the process group. Otherwise, the output generated by 7364 that process is output to the current output stream. Processes that are blocking or ignoring 7365 SIGTTOU signals are excepted and allowed to produce output, and the SIGTTOU signal is not 7366 sent. 7367 The initial local control value after open( ) is implementation-defined. | 7368 11.2.6 Special Control Characters 7369 The special control characters values are defined by the array c_cc. The subscript name and 7370 description for each element in both canonical and non-canonical modes are as follows: 7371 ______________________________________________ 7372 _ Subscript Usage ____________________________ 7373 Canonical Non-Canonical 7374 _ Mode Mode Description _____________________________________________ 7375 VEOF EOF character 7376 VEOL EOL character 7377 VERASE ERASE character 7378 VINTR VINTR INTR character 7379 VKILL KILL character 7380 VMIN MIN value 7381 VQUIT VQUIT QUIT character 7382 VSUSP VSUSP SUSP character 7383 VTIME TIME value 7384 VSTART VSTART START character 7385 _ VSTOP VSTOP STOP character _____________________________________________ 7386 The subscript values are unique, except that the VMIN and VTIME subscripts may have the 7387 same values as the VEOF and VEOL subscripts, respectively. 7388 Implementations that do not support changing the START and STOP characters may ignore the 7389 character values in the c_cc array indexed by the VSTART and VSTOP subscripts when 7390 tcsetattr( ) is called, but shall return the value in use when tcgetattr( ) is called. 224 Technical Standard (2000) (Draft July 28, 2000) General Terminal Interface Parameters that Can be Set 7391 The initial values of all control characters are implementation-defined. | 7392 If the value of one of the changeable special control characters (see Section 11.1.9 (on page 217)) 7393 is _POSIX_VDISABLE, that function shall be disabled; that is, no input data is recognized as the 7394 disabled special character. If ICANON is not set, the value of _POSIX_VDISABLE has no special 7395 meaning for the VMIN and VTIME entries of the c_cc array. Base Definitions, Issue 6 225 General Terminal Interface 7396 | 226 Technical Standard (2000) (Draft July 28, 2000) Chapter 12 Utility Conventions 7397 7398 12.1 Utility Argument Syntax 7399 This section describes the argument syntax of the standard utilities and introduces terminology 7400 used throughout IEEE Std. 1003.1-200x for describing the arguments processed by the utilities. 7401 Within IEEE Std. 1003.1-200x, a special notation is used for describing the syntax of a utility's 7402 arguments. Unless otherwise noted, all utility descriptions use this notation, which is illustrated 7403 by this example (see the Shell and Utilities volume of IEEE Std. 1003.1-200x, Section 2.9.1, Simple | 7404 Commands): | 7405 utility_name[-a][-b][-c option_argument] 7406 [-d|-e][-foption_argument][operand...] 7407 The notation used for the SYNOPSIS sections imposes requirements on the implementors of the 7408 standard utilities and provides a simple reference for the application developer or system user. 7409 1. The utility in the example is named utility_name. It is followed by options, option- 7410 arguments, and operands. The arguments that consist of hyphens and single letters or 7411 digits, such as 'a', are known as options (or, historically, flags). Certain options are 7412 followed by an option-argument, as shown with [-c option_argument]. The arguments 7413 following the last options and option-arguments are named operands. 7414 2. Option-arguments are sometimes shown separated from their options by 7415 characters, sometimes directly adjacent. This reflects the situation that in some cases an 7416 option-argument is included within the same argument string as the option; in most cases 7417 it is the next argument. The Utility Syntax Guidelines in Section 12.2 (on page 229) require 7418 that the option be a separate argument from its option-argument, but there are some 7419 exceptions in IEEE Std. 1003.1-200x to ensure continued operation of historical 7420 applications: 7421 a. If the SYNOPSIS of a standard utility shows a space character between an option and 7422 option-argument (as with [-c option_argument] in the example), a portable 7423 application shall use separate arguments for that option and its option-argument. 7424 b. If a space character is not shown (as with [-foption_argument] in the example), a 7425 portable application shall place an option and its option-argument directly adjacent 7426 in the same argument string, without intervening characters. 7427 c. Notwithstanding the preceding requirements on portable applications, a conforming 7428 system shall permit, but shall not require, an application to specify options and 7429 option-arguments as separate arguments whether or not a space character is shown 7430 XSI on the synopsis line, except in those cases (marked with the XSI portability warning) 7431 where an option-argument is optional and no separation can be used. 7432 d. A standard utility may also be implemented to operate correctly when the required 7433 separation into multiple arguments is violated by a non-portable application. 7434 In summary, the following table shows allowable combinations: Base Definitions, Issue 6 227 Utility Argument Syntax Utility Conventions 7435 ________________________________________________________________ 7436 _ SYNOPSIS Shows: __________________________________ 7437 _ -a arg -barg -c[arg] _______________________________________________________________ 7438 _ Portable application shall use: -a arg -barg N/A _______________________________________________________________ 7439 _ System shall support: -a arg -barg -carg or -c _______________________________________________________________ 7440 _ System may support: -aarg -b arg _______________________________________________________________ 7441 3. Options are usually listed in alphabetical order unless this would make the utility 7442 description more confusing. There are no implied relationships between the options based 7443 upon the order in which they appear, unless otherwise stated in the OPTIONS section, or 7444 unless the exception in Guideline 11 of Section 12.2 (on page 229) applies. If an option that 7445 does not have option-arguments is repeated, the results are undefined, unless otherwise 7446 stated. 7447 4. Frequently, names of parameters that require substitution by actual values are shown with 7448 embedded underscores. Alternatively, parameters are shown as follows: 7449 7450 The angle brackets are used for the symbolic grouping of a phrase representing a single 7451 parameter and portable applications shall not include them in data submitted to the utility. 7452 5. When a utility has only a few permissible options, they are sometimes shown individually, 7453 as in the example. Utilities with many flags generally show all of the individual flags (that 7454 do not take option-arguments) grouped, as in: 7455 utility_name [-abcDxyz][-p arg][operand] 7456 Utilities with very complex arguments may be shown as follows: 7457 utility_name [options][operands] 7458 6. Unless otherwise specified, whenever an operand or option-argument is, or contains, a 7459 numeric value: 7460 * The number is interpreted as a decimal integer. 7461 * Numerals in the range 0 to 2 147 483 647 are syntactically recognized as numeric values. 7462 * When the utility description states that it accepts negative numbers as operands or 7463 option-arguments, numerals in the range -2 147 483 647 to 2 147 483 647 are 7464 syntactically recognized as numeric values. 7465 * Ranges greater than those listed here are allowed. 7466 This does not mean that all numbers within the allowable range are necessarily 7467 semantically correct. A standard utility that accepts an option-argument or operand that is 7468 to be interpreted as a number, and for which a range of values smaller than that shown 7469 above is permitted by the IEEE Std. 1003.1-200x, describes that smaller range along with 7470 the description of the option-argument or operand. If an error is generated, the utility's 7471 diagnostic message shall indicate that the value is out of the supported range, not that it is 7472 syntactically incorrect. | 7473 7. Arguments or option-arguments enclosed in the '[' and ']' notation are optional and 7474 can be omitted. Portable applications shall not include the '[' and ']' symbols in data 7475 submitted to the utility. 7476 8. Arguments separated by the '|' vertical bar notation are mutually-exclusive. Portable 7477 applications shall not include the '|' symbol in data submitted to the utility. 7478 Alternatively, mutually-exclusive options and operands may be listed with multiple 228 Technical Standard (2000) (Draft July 28, 2000) Utility Conventions Utility Argument Syntax 7479 synopsis lines. For example: 7480 utility_name -d[-a][-c option_argument][operand...] 7481 utility_name[-a][-b][operand...] 7482 When multiple synopsis lines are given for a utility, it is an indication that the utility has 7483 mutually-exclusive arguments. These mutually-exclusive arguments alter the functionality 7484 of the utility so that only certain other arguments are valid in combination with one of the 7485 mutually-exclusive arguments. Only one of the mutually-exclusive arguments is allowed 7486 for invocation of the utility. Unless otherwise stated in an accompanying OPTIONS 7487 section, the relationships between arguments depicted in the SYNOPSIS sections are 7488 mandatory requirements placed on portable applications. The use of conflicting mutually- 7489 exclusive arguments produces undefined results, unless a utility description specifies 7490 otherwise. When an option is shown without the '[' and ']' brackets, it means that 7491 option is required for that version of the SYNOPSIS. However, it is not required to be the 7492 first argument, as shown in the example above, unless otherwise stated. | 7493 9. Ellipses ("...") are used to denote that one or more occurrences of an option or operand 7494 are allowed. When an option or an operand followed by ellipses is enclosed in brackets, 7495 zero or more options or operands can be specified. The forms: 7496 utility_name -f option_argument...[operand...] 7497 utility_name [-g option_argument]...[operand...] 7498 indicate that multiple occurrences of the option and its option-argument preceding the 7499 ellipses are valid, with semantics as indicated in the OPTIONS section of the utility. (See 7500 also Guideline 11 in Section 12.2.) In the first example, each option-argument requires a 7501 preceding -f and at least one -f option_argument must be given. | 7502 10. When the synopsis line is too long to be printed on a single line in the Shell and Utilities | 7503 volume of IEEE Std. 1003.1-200x, the indented lines following the initial line are | 7504 continuation lines. An actual use of the command would appear on a single logical line. 7505 12.2 Utility Syntax Guidelines 7506 The following guidelines are established for the naming of utilities and for the specification of 7507 options, option-arguments, and operands. The getopt( ) function in the System Interfaces volume 7508 of IEEE Std. 1003.1-200x assists utilities in handling options and operands that conform to these 7509 guidelines. 7510 Operands and option-arguments can contain characters not specified in the portable character 7511 set. 7512 The guidelines are intended to provide guidance to the authors of future utilities, such as those 7513 written specific to a local system or that are components of a larger application. Some of the 7514 standard utilities do not conform to all of these guidelines; in those cases, the OPTIONS sections 7515 describe the deviations. 7516 Guideline 1: Utility names should be between two and nine characters, inclusive. 7517 Guideline 2: Utility names should include lowercase letters (the lower character 7518 classification) and digits only from the portable character set. | 7519 Guideline 3: Each option name should be a single alphanumeric character (the alnum 7520 character classification) from the portable character set. Base Definitions, Issue 6 229 Utility Syntax Guidelines Utility Conventions 7521 Multi-digit options are not allowed. 7522 Guideline 4: All options should be preceded by the '-' delimiter character. 7523 Guideline 5: Options without option-arguments should be accepted when grouped behind 7524 one '-' delimiter. 7525 Guideline 6: Each option and option-argument should be a separate argument, except as 7526 noted in Section 12.1 (on page 227), item (2). 7527 Guideline 7: Option-arguments should not be optional. 7528 Guideline 8: When multiple option-arguments are specified to follow a single option, they 7529 should be presented as a single argument, using commas within that 7530 argument or characters within that argument to separate them. | 7531 Guideline 9: All options should precede operands on the command line. 7532 Guideline 10: The argument - - should be accepted as a delimiter indicating the end of 7533 options. Any following arguments should be treated as operands, even if they 7534 begin with the '-' character. The - - argument should not be used as an 7535 option or as an operand. | 7536 Guideline 11: The order of different options relative to one another should not matter, 7537 unless the options are documented as mutually-exclusive and such an option 7538 is documented to override any incompatible options preceding it. If an option 7539 that has option-arguments is repeated, the option and option-argument 7540 combinations should be interpreted in the order specified on the command 7541 line. | 7542 Guideline 12: The order of operands may matter and position-related interpretations should 7543 be determined on a utility-specific basis. 7544 Guideline 13: For utilities that use operands to represent files to be opened for either reading 7545 or writing, the '-' operand should be used only to mean standard input (or 7546 standard output when it is clear from context that an output file is being 7547 specified). | 7548 The utilities in the Shell and Utilities volume of IEEE Std. 1003.1-200x that claim conformance to | 7549 these guidelines shall conform completely to these guidelines as if these guidelines contained the | 7550 term ``shall'' instead of ``should''. On some systems, the utilities accept usage in violation of 7551 these guidelines for backward compatibility as well as accepting the required form. 7552 It is recommended that all future utilities and applications use these guidelines to enhance user 7553 portability. The fact that some historical utilities could not be changed (to avoid breaking 7554 existing applications) should not deter this future goal. 230 Technical Standard (2000) (Draft July 28, 2000) Chapter 13 Headers 7555 7556 This chapter describes the contents of headers. 7557 Headers contain function prototypes, the definition of symbolic constants, common structures, 7558 preprocessor macros, and defined types. Each function in the System Interfaces volume of 7559 IEEE Std. 1003.1-200x specifies the headers that an application shall include in order to use that 7560 function. In most cases, only one header is required. These headers are present on an application | 7561 development system; they need not be present on the target execution system. | 7562 13.1 Format of Entries 7563 The entries in this chapter are based on a common format as follows. The only sections relating 7564 to conformance are the SYNOPSIS and DESCRIPTION. 7565 NAME 7566 This section gives the name or names of the entry and briefly states its purpose. 7567 SYNOPSIS 7568 This section summarizes the use of the entry being described. 7569 DESCRIPTION 7570 This section describes the functionality of the header. 7571 APPLICATION USAGE 7572 This section is non-normative. 7573 This section gives warnings and advice to application writers about the entry. In the 7574 event of conflict between warnings and advice and a normative part of this volume of 7575 IEEE Std. 1003.1-200x, the normative material is to be taken as correct. 7576 RATIONALE 7577 This section is non-normative. 7578 This section contains historical information concerning the contents of this volume of 7579 IEEE Std. 1003.1-200x and why features were included or discarded by the standard 7580 developers. 7581 FUTURE DIRECTIONS 7582 This section is non-normative. 7583 This section provides comments which should be used as a guide to current thinking; 7584 there is not necessarily a commitment to adopt these future directions. 7585 SEE ALSO 7586 This section is non-normative. 7587 This section gives references to related information. 7588 CHANGE HISTORY 7589 This section is non-normative. 7590 This section shows the derivation of the entry and any significant changes that have 7591 been made to it. Base Definitions, Issue 6 231 Headers 7592 NAME 7593 aio.h - asynchronous input and output (REALTIME) | 7594 SYNOPSIS 7595 AIO #include 7596 7597 DESCRIPTION 7598 The header shall define the aiocb structure which shall include at least the following 7599 members: 7600 int aio_fildes File descriptor. 7601 off_t aio_offset File offset. 7602 volatile void *aio_buf Location of buffer. 7603 size_t aio_nbytes Length of transfer. 7604 int aio_reqprio Request priority offset. 7605 struct sigevent aio_sigevent Signal number and value. 7606 int aio_lio_opcode Operation to be performed. 7607 This header shall also include the following constants: 7608 AIO_CANCELED A return value indicating that all requested operations have been 7609 canceled. 7610 AIO_NOTCANCELED 7611 A return value indicating that some of the requested operations could not 7612 be canceled since they are in progress. 7613 AIO_ALLDONE A return value indicating that none of the requested operations could be 7614 canceled since they are already complete. 7615 LIO_WAIT A lio_listio ( ) synchronization operation indicating that the calling thread 7616 is to suspend until the lio_listio ( ) operation is complete. 7617 LIO_NOWAIT A lio_listio ( ) synchronization operation indicating that the calling thread 7618 is to continue execution while the lio_listio ( ) operation is being 7619 performed, and no notification is given when the operation is complete. 7620 LIO_READ A lio_listio ( ) element operation option requesting a read. 7621 LIO_WRITE A lio_listio ( ) element operation option requesting a write. 7622 LIO_NOP A lio_listio ( ) element operation option indicating that no transfer is 7623 requested. 7624 The following shall be declared as functions and may also be declared as macros. Function 7625 prototypes shall be provided for use with an ISO C standard compiler. 7626 int aio_cancel(int, struct aiocb *); 7627 int aio_error(const struct aiocb *); 7628 int aio_fsync(int, struct aiocb *); 7629 int aio_read(struct aiocb *); 7630 ssize_t aio_return(struct aiocb *); 7631 int aio_suspend(const struct aiocb *const[], int, 7632 const struct timespec *); 7633 int aio_write(struct aiocb *); 7634 int lio_listio(int, struct aiocb *restrict const[restrict], int, 7635 struct sigevent *restrict); 232 Technical Standard (2000) (Draft July 28, 2000) Headers 7636 Inclusion of the header may make visible symbols defined in the headers , 7637 , , and . 7638 APPLICATION USAGE 7639 None. 7640 RATIONALE 7641 None. 7642 FUTURE DIRECTIONS 7643 None. 7644 SEE ALSO 7645 , , , , the System Interfaces volume of 7646 IEEE Std. 1003.1-200x, fsync( ), lseek( ), read( ), write( ) 7647 CHANGE HISTORY 7648 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 7649 Issue 6 7650 The header is marked as part of the Asynchronous Input and Output option. | 7651 The description of the constants is expanded. | 7652 The restrict keyword is added to the prototype for lio_listio ( ). | Base Definitions, Issue 6 233 Headers 7653 NAME 7654 arpa/inet.h - definitions for internet operations 7655 SYNOPSIS 7656 #include 7657 DESCRIPTION 7658 The in_port_t and in_addr_t types shall be defined as described in . | 7659 The in_addr structure shall be defined as described in . 7660 The INET_ADDRSTRLEN and INET6_ADDRSTRLEN macros shall be defined as described in 7661 . 7662 The following shall be declared as functions, defined as macros, or both. If functions are | 7663 declared, function prototypes shall be provided for use with an ISO C standard compiler. | 7664 uint32_t htonl(uint32_t); 7665 uint16_t htons(uint16_t); 7666 uint32_t ntohl(uint32_t); 7667 uint16_t ntohs(uint16_t); 7668 The uint32_t and uint16_t types shall be defined as described in . 7669 The following shall be declared as functions, and may also be defined as macros. Function 7670 prototypes shall be provided for use with an ISO C standard compiler. 7671 in_addr_t inet_addr(const char *); 7672 in_addr_t inet_lnaof(struct in_addr); 7673 struct in_addr inet_makeaddr(in_addr_t, in_addr_t); 7674 in_addr_t inet_netof(struct in_addr); 7675 in_addr_t inet_network(const char *); 7676 char *inet_ntoa(struct in_addr); 7677 IP6 const char *inet_ntop(int, const void *restrict, char *restrict, 7678 socklen_t); 7679 int inet_pton(int, const char *restrict, void *restrict); 7680 7681 Inclusion of the header may also make visible all symbols from 7682 and . 7683 APPLICATION USAGE 7684 None. 7685 RATIONALE 7686 None. 7687 FUTURE DIRECTIONS 7688 None. 7689 SEE ALSO 7690 , , the System Interfaces volume of IEEE Std. 1003.1-200x, htonl( ), 7691 inet_addr( ) 7692 CHANGE HISTORY 7693 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. | 7694 The restrict keyword is added to the prototypes for inet_ntop( ) and inet_pton( ). | 234 Technical Standard (2000) (Draft July 28, 2000) Headers 7695 NAME 7696 assert.h - verify program assertion 7697 SYNOPSIS 7698 #include 7699 DESCRIPTION 7700 CX The functionality described on this reference page extends the ISO C standard. Applications 7701 shall define the appropriate feature test macro (see the System Interfaces volume of 7702 IEEE Std. 1003.1-200x, Section 2.2, The Compilation Environment) to enable the visibility of 7703 symbols in this header. 7704 The header shall define the assert( ) macro. It refers to the macro NDEBUG which is | 7705 not defined in the header. If NDEBUG is defined as a macro name before the inclusion of this | 7706 header, the assert( ) macro is defined simply as: | 7707 #define assert(ignore)((void) 0) 7708 Otherwise, the macro behaves as described in assert( ). | 7709 The assert( ) macro is redefined according to the current state of NDEBUG each time | 7710 is included. | 7711 The assert( ) macro is implemented as a macro, not as a function. If the macro definition is | 7712 suppressed in order to access an actual function, the behavior is undefined. 7713 APPLICATION USAGE 7714 None. 7715 RATIONALE 7716 None. 7717 FUTURE DIRECTIONS 7718 None. 7719 SEE ALSO 7720 The System Interfaces volume of IEEE Std. 1003.1-200x, assert( ) 7721 CHANGE HISTORY 7722 First released in Issue 1. Derived from Issue 1 of the SVID. | 7723 Issue 6 | 7724 The definition of the assert( ) macro is changed for alignment with the ISO/IEC 9899: 1999 || 7725 standard. | Base Definitions, Issue 6 235 Headers 7726 NAME | 7727 complex.h - complex arithmetic | 7728 SYNOPSIS | 7729 #include | 7730 DESCRIPTION | 7731 CX The functionality described on this reference page extends the ISO C standard. Applications | 7732 shall define the appropriate feature test macro (see the System Interfaces volume of | 7733 IEEE Std. 1003.1-200x, Section 2.2, The Compilation Environment) to enable the visibility of | 7734 symbols in this header. | 7735 The header shall define the following constants: | 7736 complex Expands to _Complex. | 7737 _Complex_I Expands to a constant expression of type const float _Complex, with the value | 7738 of the imaginary unit (that is, a number such that i2=-1). | 7739 imaginary Expands to _Imaginary. | 7740 _Imaginary_I Expands to a constant expression of type const float _Imaginary with the value | 7741 of the imaginary unit. | 7742 I Expands to either _Imaginary_I or _Complex_I. If _Imaginary_I is not defined, I | 7743 expands to _Complex_I. | 7744 The constants imaginary and _Imaginary_I shall be defined if the implementation supports | 7745 imaginary types. | 7746 An application may undefine and then, perhaps, redefine the complex, imaginary, and I constants. | 7747 The following shall be declared as functions and may also be defined as macros. Function | 7748 prototypes shall be provided for use with an ISO C standard compiler. | 7749 double complex cacos(double complex); | 7750 float complex cacosf(float complex); | 7751 long double complex cacosl(long double complex); | 7752 double complex casin(double complex); | 7753 float complex casinf(float complex); | 7754 long double complex casinl(long double complex); | 7755 double complex catan(double complex); | 7756 float complex catanf(float complex); | 7757 long double complex catanl(long double complex); | 7758 double complex ccos(double complex); | 7759 float complex ccosf(float complex); | 7760 long double complex ccosl(long double complex); | 7761 double complex csin(double complex); | 7762 float complex csinf(float complex); | 7763 long double complex csinl(long double complex); | 7764 double complex ctan(double complex); | 7765 float complex ctanf(float complex); | 7766 long double complex ctanl(long double complex); | 7767 double complex cacosh(double complex); | 7768 float complex cacoshf(float complex); | 7769 long double complex cacoshl(long double complex); | 7770 double complex casinh(double complex); | 7771 float complex casinhf(float complex); | 236 Technical Standard (2000) (Draft July 28, 2000) Headers 7772 long double complex casinhl(long double complex); | 7773 double complex catanh(double complex); | 7774 float complex catanhf(float complex); | 7775 long double complex catanhl(long double complex); | 7776 double complex ccosh(double complex); | 7777 float complex ccoshf(float complex); | 7778 long double complex ccoshl(long double complex); | 7779 double complex csinh(double complex); | 7780 float complex csinhf(float complex); | 7781 long double complex csinhl(long double complex); | 7782 double complex catanh(double complex); | 7783 float complex catanhf(float complex); | 7784 long double complex catanhl(long double complex); | 7785 double complex cexp(double complex); | 7786 float complex cexpf(float complex); | 7787 long double complex cexpl(long double complex); | 7788 double complex clog(double complex); | 7789 float complex clogf(float complex); | 7790 long double complex clogl(long double complex); | 7791 double cabs(double complex); | 7792 float cabsf(float complex); | 7793 long double cabsl(long double complex); | 7794 double complex cpow(double complex, double complex); | 7795 float complex cpowf(float complex, float complex); | 7796 long double complex cpowl(long double complex, long double complex); | 7797 double complex csqrt(double complex); | 7798 float complex csqrtf(float complex); | 7799 long double complex csqrtl(long double complex); | 7800 double carg(double complex); | 7801 float cargf(float complex); | 7802 long double cargl(long double complex); | 7803 double cimag(double complex); | 7804 float cimagf(float complex); | 7805 long double cimagl(long double complex); | 7806 double complex conj(double complex); | 7807 float complex conjf(float complex); | 7808 long double complex conjl(long double complex); | 7809 double complex cproj(double complex); | 7810 float complex cprojf(float complex); | 7811 long double complex cprojl(long double complex); | 7812 double creal(double complex); | 7813 float crealf(float complex); | 7814 long double creall(long double complex); | Base Definitions, Issue 6 237 Headers 7815 APPLICATION USAGE | 7816 Values are interpreted as radians, not degrees. An implementation may set errno, but is not | 7817 required to. | 7818 Some of the complex arithmetic functions have branch cuts, across which the function is | 7819 discontinuous. For implementations with a signed zero (including all IEC 60559: 1989 standard | 7820 implementations), the sign of zero distinguishes one side of a cut from another so the function is | 7821 continuous (except for format limitations) as the cut is approached from either side. For | 7822 example, for the square root function, which has a branch cut along the negative real axis, the | 7823 top of the cut, with imaginary part +0, maps to the positive imaginary axis, and the bottom of | 7824 the cut, with imaginary part -0, maps to the negative imaginary axis. | 7825 Implementations that do not support a signed zero cannot distinguish the sides of branch cuts. | 7826 These implementations shall map a cut so the function is continuous as the cut is approached | 7827 coming around the finite endpoint of the cut in a counter-clockwise direction. (Branch cuts for | 7828 the functions specified here have just one finite endpoint.) For example, for the square root | 7829 function, coming counter-clockwise around the finite endpoint of the cut along the negative real | 7830 axis approaches the cut from above, so the cut maps to the positive imaginary axis. | 7831 The usual mathematical formulas for complex multiply, divide, and absolute value are | 7832 problematic because of their treatment of infinities and because of undue overflow and | 7833 underflow. The CX_LIMITED_RANGE pragma can be used to inform the implementation that | 7834 (where the state is on) the usual mathematical formulas are acceptable. The pragma can occur | 7835 either outside external declarations or preceding all explicit declarations and statements inside a | 7836 compound statement. When outside external declarations, the pragma takes effect from its | 7837 occurrence until another CX_LIMITED_RANGE pragma is encountered, or until the end of the | 7838 translation unit. When inside a compound statement, the pragma takes effect from its | 7839 occurrence until another CX_LIMITED_RANGE pragma is encountered (including within a | 7840 nested compound statement), or until the end of the compound statement; at the end of a | 7841 compound statement the state for the pragma is restored to its condition just before the | 7842 compound statement. If this pragma is used in any other context, the behavior is undefined. The | 7843 default state for the pragma is off. | 7844 RATIONALE | 7845 The choice of I instead of i for the imaginary unit concedes to the widespread use of the | 7846 identifier i for other purposes. The application can use a different identifier, say j, for the | 7847 imaginary unit by following the inclusion of the header with: | 7848 #undef I | 7849 #define j _Imaginary_I | 7850 An I suffix to designate imaginary constants is not required, as multiplication by I provides a | 7851 sufficiently convenient and more generally useful notation for imaginary terms. The | 7852 corresponding real type for the imaginary unit is float, so that use of I for algorithmic or | 7853 notational convenience will not result in widening types. | 7854 On systems with imaginary types, the application has the ability to control whether use of the | 7855 macro I introduces an imaginary type, by explicitly defining I to be _Imaginary_I or _Complex_I. | 7856 Disallowing imaginary types is useful for some applications intended to run on implementations | 7857 without support for such types. | 7858 The macro _Imaginary_I provides a test for whether imaginary types are supported. | 7859 The cis( ) function (cos(x) + I*sin(x)) was considered but rejected because its implementation is | 7860 easy and straightforward, even though some implementations could compute sine and cosine | 7861 more efficiently in tandem. | 238 Technical Standard (2000) (Draft July 28, 2000) Headers 7862 FUTURE DIRECTIONS | 7863 The following function names and the same names suffixed with f or l are reserved for future | 7864 use, and may be added to the declarations in the header. | 7865 cerf( ) cexpm1( ) clog2( ) |||| 7866 cerfc( ) clog10( ) clgamma( ) ||| 7867 cexp2( ) clog1p( ) ctgamma( ) ||| 7868 SEE ALSO | 7869 The System Interfaces volume of IEEE Std. 1003.1-200x, cabs( ), cacos( ), cacosh( ), carg( ), casin( ), | 7870 casinh( ), catan( ), catanh( ), ccos( ), ccosh( ), cexp( ), cimag( ), clog( ), conj( ), cpow( ), cproj( ), creal( ), | 7871 csin( ), csinh( ), csqrt( ), ctan( ), ctanh( ) | 7872 CHANGE HISTORY | 7873 First released in Issue 6. Included for alignment with the ISO/IEC 9899: 1999 standard. | Base Definitions, Issue 6 239 Headers 7874 NAME 7875 cpio.h - cpio archive values 7876 SYNOPSIS 7877 XSI #include 7878 7879 DESCRIPTION 7880 Values needed by the c_mode field of the cpio archive format are described as follows: 7881 ________________________________________________________________ 7882 _ Name Description Value (Octal) _______________________________________________________________ 7883 C_IRUSR Read by owner. 0000400 7884 C_IWUSR Write by owner. 0000200 7885 C_IXUSR Execute by owner. 0000100 7886 C_IRGRP Read by group. 0000040 7887 C_IWGRP Write by group. 0000020 7888 C_IXGRP Execute by group. 0000010 7889 C_IROTH Read by others. 0000004 7890 C_IWOTH Write by others. 0000002 7891 C_IXOTH Execute by others. 0000001 7892 C_ISUID Set user ID. 0004000 7893 C_ISGID Set group ID. 0002000 7894 C_ISVTX On directories, restricted deletion flag. 0001000 7895 C_ISDIR Directory. 0040000 7896 C_ISFIFO FIFO. 0010000 7897 C_ISREG Regular file. 0100000 7898 C_ISBLK Block special. 0060000 7899 C_ISCHR Character special. 0020000 7900 C_ISCTG Reserved. 0110000 7901 C_ISLNK Symbolic link. 0120000 7902 _ C_ISSOCK Socket. 0140000 _______________________________________________________________ 7903 The header shall define the symbolic constant: 7904 MAGIC "070707" 7905 APPLICATION USAGE 7906 None. 7907 RATIONALE 7908 None. 7909 FUTURE DIRECTIONS 7910 None. 7911 SEE ALSO 7912 The Shell and Utilities volume of IEEE Std. 1003.1-200x, pax | 7913 CHANGE HISTORY 7914 First released in Issue 3 of the Headers Interface, Issue 3 specification. Derived from the | 7915 POSIX.1-1988 standard. | 7916 Issue 4, Version 2 7917 Descriptions for C_ISLNK and C_ISSOCK are provided; formerly, these were listed as 7918 ``Reserved''. 240 Technical Standard (2000) (Draft July 28, 2000) Headers 7919 Issue 6 7920 The SEE ALSO is updated to refer to pax, since the cpio utility is not included in the Shell and | 7921 Utilities volume of IEEE Std. 1003.1-200x. | Base Definitions, Issue 6 241 Headers 7922 NAME 7923 ctype.h - character types 7924 SYNOPSIS 7925 #include 7926 DESCRIPTION 7927 CX The functionality described on this reference page extends the ISO C standard. Applications 7928 shall define the appropriate feature test macro (see the System Interfaces volume of 7929 IEEE Std. 1003.1-200x, Section 2.2, The Compilation Environment) to enable the visibility of 7930 symbols in this header. 7931 The header shall declare the following as functions and may also define them as 7932 macros. Function prototypes shall be provided for use with an ISO C standard compiler. 7933 int isalnum(int); 7934 int isalpha(int); 7935 XSI int isascii(int); 7936 int isblank(int); 7937 int iscntrl(int); 7938 int isdigit(int); 7939 int isgraph(int); 7940 int islower(int); 7941 int isprint(int); 7942 int ispunct(int); 7943 int isspace(int); 7944 int isupper(int); 7945 int isxdigit(int); 7946 XSI int toascii(int); 7947 int tolower(int); 7948 int toupper(int); 7949 The following are defined as macros: 7950 XSI int _toupper(int); 7951 int _tolower(int); 7952 7953 APPLICATION USAGE 7954 None. 7955 RATIONALE 7956 None. 7957 FUTURE DIRECTIONS 7958 None. 7959 SEE ALSO 7960 , the System Interfaces volume of IEEE Std. 1003.1-200x, isalnum( ), isalpha( ), isascii( ), 7961 iscntrl( ), isdigit( ), isgraph( ), islower( ), isprint( ), ispunct( ), isspace( ), isupper( ), isxdigit( ), mblen( ), 7962 mbstowcs( ), mbtowc( ), setlocale( ), toascii( ), tolower( ), _tolower( ), toupper( ), _toupper( ), wcstombs( ), 7963 wctomb( ) 7964 CHANGE HISTORY 7965 First released in Issue 1. Derived from Issue 1 of the SVID. | 242 Technical Standard (2000) (Draft July 28, 2000) Headers 7966 Issue 4 7967 The following change is incorporated for alignment with the ISO POSIX-1 standard: 7968 * The function declarations in this header are expanded to full ISO C standard prototypes. 7969 Issue 6 7970 Extensions beyond the ISO C standard are now marked. Base Definitions, Issue 6 243 Headers 7971 NAME 7972 dirent.h - format of directory entries 7973 SYNOPSIS 7974 #include 7975 DESCRIPTION 7976 The internal format of directories is unspecified. 7977 The header shall define the following data type through typedef: 7978 DIR A type representing a directory stream. 7979 It shall also define the structure dirent which shall include the following members: 7980 XSI ino_t d_ino File serial number. 7981 char d_name[] Name of entry. 7982 XSI The type ino_t shall be defined as described in . 7983 The character array d_name is of unspecified size, but the number of bytes preceding the 7984 terminating null byte does not exceed {NAME_MAX}. 7985 The following shall be declared as functions and may also be defined as macros. Function 7986 prototypes shall be provided for use with an ISO C standard compiler. 7987 int closedir(DIR *); 7988 DIR *opendir(const char *); 7989 struct dirent *readdir(DIR *); 7990 TSF int readdir_r(DIR *restrict, struct dirent *restrict, 7991 struct dirent **restrict); 7992 void rewinddir(DIR *); 7993 XSI void seekdir(DIR *, long); 7994 long telldir(DIR *); 7995 7996 APPLICATION USAGE 7997 None. 7998 RATIONALE 7999 Information similar to that in the header is contained in a file in 4.2 BSD 8000 and 4.3 BSD. The equivalent in these implementations of struct dirent from this volume of 8001 IEEE Std. 1003.1-200x is struct direct. The file name was changed because the name 8002 was also used in earlier implementations to refer to definitions related to the older access 8003 method; this produced name conflicts. The name of the structure was changed because this 8004 volume of IEEE Std. 1003.1-200x does not completely define what is in the structure, so it could 8005 be different on some implementations from struct direct. 8006 The name of an array of char of an unspecified size should not be used as an lvalue. Use of: 8007 sizeof(d_name) 8008 is incorrect; use: 8009 strlen(d_name) 8010 instead. 8011 The array of char d_name is not a fixed size. Implementations may need to declare struct dirent 8012 with an array size for d_name of 1, but the actual number of characters provided matches (or 8013 only slightly exceeds) the length of the file name. | 244 Technical Standard (2000) (Draft July 28, 2000) Headers 8014 FUTURE DIRECTIONS 8015 None. 8016 SEE ALSO 8017 , the System Interfaces volume of IEEE Std. 1003.1-200x, closedir( ), opendir( ), 8018 readdir( ), readdir_r( ), rewinddir( ), seekdir( ), telldir( ) 8019 CHANGE HISTORY 8020 First released in Issue 2. 8021 Issue 4 8022 Reference to type ino_t is marked as an extension, as are references to the seekdir( ) and telldir( ) 8023 functions. 8024 The following changes are incorporated for alignment with the ISO POSIX-1 standard: 8025 * The function declarations in this header are expanded to full ISO C standard prototypes. 8026 * A statement is added to the DESCRIPTION indicating that the internal format of directories 8027 is unspecified. Also in the description of the d_name field, the text is changed to indicate 8028 ``bytes'' rather than (possibly multi-byte) ``characters''. 8029 Issue 5 8030 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 8031 Issue 6 8032 The Open Group corrigenda item U026/7 has been applied, correcting the prototype for 8033 readdir_r( ). | 8034 The restrict keyword is added to the prototype for readdir_r( ). | Base Definitions, Issue 6 245 Headers 8035 NAME 8036 dlfcn.h - dynamic linking 8037 SYNOPSIS 8038 XSI #include 8039 8040 DESCRIPTION 8041 The header shall define at least the following macros for use in the construction of a 8042 dlopen( ) mode argument: 8043 RTLD_LAZY Relocations are performed at an implementation-defined time. | 8044 RTLD_NOW Relocations are performed when the object is loaded. 8045 RTLD_GLOBAL All symbols are available for relocation processing of other modules. 8046 RTLD_LOCAL All symbols are not made available for relocation processing by other 8047 modules. 8048 The header shall declare the following functions which may also be defined as 8049 macros. Function prototypes shall be provided for use with an ISO C standard compiler. 8050 int dlclose(void *); 8051 char *dlerror(void); 8052 void *dlopen(const char *, int); 8053 void *dlsym(void *restrict, const char *restrict); 8054 APPLICATION USAGE 8055 None. 8056 RATIONALE 8057 None. 8058 FUTURE DIRECTIONS 8059 None. 8060 SEE ALSO 8061 The System Interfaces volume of IEEE Std. 1003.1-200x, dlopen( ), dlclose( ), dlsym( ), dlerror( ) 8062 CHANGE HISTORY 8063 First released in Issue 5. | 8064 Issue 6 | 8065 The restrict keyword is added to the prototype for dlsym( ). | 246 Technical Standard (2000) (Draft July 28, 2000) Headers 8066 NAME 8067 errno.h - system error numbers 8068 SYNOPSIS 8069 #include 8070 DESCRIPTION 8071 CX The functionality described on this reference page extends the ISO C standard. Applications 8072 shall define the appropriate feature test macro (see the System Interfaces volume of 8073 IEEE Std. 1003.1-200x, Section 2.2, The Compilation Environment) to enable the visibility of 8074 symbols in this header. | 8075 The header provides a declaration for errno and gives non-zero values for the 8076 following symbolic constants. Their values are unique except as noted below: | 8077 [E2BIG] Argument list too long. 8078 [EACCES] Permission denied. | 8079 [EADDRINUSE] Address in use. | 8080 [EADDRNOTAVAIL] Address not available. | 8081 [EAFNOSUPPORT] Address family not supported. | 8082 [EAGAIN] Resource unavailable, try again (may be the same value as | 8083 [EWOULDBLOCK]). | 8084 [EALREADY] Connection already in progress. | 8085 [EBADF] Bad file descriptor. 8086 [EBADMSG] Bad message. 8087 [EBUSY] Device or resource busy. 8088 [ECANCELED] Operation canceled. 8089 [ECHILD] No child processes. | 8090 [ECONNABORTED] Connection aborted. | 8091 [ECONNREFUSED] Connection refused. | 8092 [ECONNRESET] Connection reset. | 8093 [EDEADLK] Resource deadlock would occur. | 8094 [EDESTADDRREQ] Destination address required. | 8095 [EDOM] Mathematics argument out of domain of function. | 8096 [EDQUOT] Reserved. | 8097 [EEXIST] File exists. 8098 [EFAULT] Bad address. 8099 [EFBIG] File too large. | 8100 [EHOSTUNREACH] Host is unreachable. | 8101 [EIDRM] Identifier removed. | 8102 [EILSEQ] Illegal byte sequence. | Base Definitions, Issue 6 247 Headers 8103 [EINPROGRESS] Operation in progress. | 8104 [EINTR] Interrupted function. 8105 [EINVAL] Invalid argument. 8106 [EIO] I/O error. | 8107 [EISCONN] Socket is connected. | 8108 [EISDIR] Is a directory. | 8109 [ELOOP] Too many levels of symbolic links. | 8110 [EMFILE] Too many open files. 8111 [EMLINK] Too many links. 8112 [EMSGSIZE] Message too large. | 8113 [EMULTIHOP] Reserved. | 8114 [ENAMETOOLONG] File name too long. | 8115 [ENETDOWN] Network is down. | 8116 [ENETUNREACH] Network unreachable. | 8117 [ENFILE] Too many files open in system. | 8118 [ENOBUFS] No buffer space available. | 8119 XSI [ENODATA] No message is available on the STREAM head read queue. 8120 [ENODEV] No such device. 8121 [ENOENT] No such file or directory. 8122 [ENOEXEC] Executable file format error. 8123 [ENOLCK] No locks available. | 8124 [ENOLINK] Reserved. | 8125 [ENOMEM] Not enough space. | 8126 [ENOMSG] No message of the desired type. | 8127 [ENOPROTOOPT] Protocol not available. | 8128 [ENOSPC] No space left on device. 8129 XSI [ENOSR] No STREAM resources. 8130 XSI [ENOSTR] Not a STREAM. 8131 [ENOSYS] Function not supported. | 8132 [ENOTCONN] The socket is not connected. | 8133 [ENOTDIR] Not a directory. 8134 [ENOTEMPTY] Directory not empty. | 8135 [ENOTSOCK] Not a socket. | 8136 [ENOTSUP] Not supported. 248 Technical Standard (2000) (Draft July 28, 2000) Headers 8137 [ENOTTY] Inappropriate I/O control operation. 8138 [ENXIO] No such device or address. | 8139 [EOPNOTSUPP] Operation not supported on socket. | 8140 [EOVERFLOW] Value too large to be stored in data type. | 8141 [EPERM] Operation not permitted. 8142 [EPIPE] Broken pipe. | 8143 [EPROTO] Protocol error. | 8144 [EPROTONOSUPPORT] | 8145 Protocol not supported. | 8146 [EPROTOTYPE] Socket type not supported. | 8147 [ERANGE] Result too large. 8148 [EROFS] Read-only file system. 8149 [ESPIPE] Invalid seek. 8150 [ESRCH] No such process. | 8151 [ESTALE] Reserved. | 8152 XSI [ETIME] Stream ioctl( ) timeout. | 8153 [ETIMEDOUT] Connection timed out. | 8154 [ETXTBSY] Text file busy. | 8155 [EWOULDBLOCK] Operation would block (may be the same value as [EAGAIN]). | 8156 [EXDEV] Cross-device link. 8157 APPLICATION USAGE 8158 Additional error numbers may be defined on conforming systems; see the System Interfaces 8159 volume of IEEE Std. 1003.1-200x. 8160 RATIONALE 8161 None. 8162 FUTURE DIRECTIONS 8163 None. 8164 SEE ALSO 8165 The System Interfaces volume of IEEE Std. 1003.1-200x, Section 2.3, Error Numbers 8166 CHANGE HISTORY 8167 First released in Issue 1. Derived from Issue 1 of the SVID. | 8168 Issue 4 8169 The [EILSEQ] error is added and marked as an EX interface. 8170 The [ENOTBLK] error is withdrawn. 8171 Issue 4, Version 2 8172 The [EADDRINUSE], [EADDRNOTAVAIL], [EAFNOSUPPORT], [EALREADY], [EBADMSG], 8173 [ECONNABORTED], [ECONNREFUSED], [ECONNRESET], [EDESTADDRREQ], [EDQUOT], 8174 [EHOSTUNREACH], [EINPROGRESS], [EISCONN], [ELOOP], [EMSGSIZE], [EMULTIHOP], 8175 [ENETDOWN], [ENETUNREACH], [ENOBUFS], [ENODATA], [ENOLINK], Base Definitions, Issue 6 249 Headers 8176 [ENOPROTOOPT], [ENOSR], [ENOSTR], [ENOTCONN], [ENOTSOCK], [EOPNOTSUPP], 8177 [EOVERFLOW], [EPROTO], [EPROTONOSUPPORT], [EPROTOTYPE], [ESTALE], [ETIME], 8178 [ETIMEDOUT], and [EWOULDBLOCK] errors are added in the UX context. 8179 Issue 5 8180 Updated for alignment with the POSIX Realtime Extension. 8181 Issue 6 8182 The following new requirements on POSIX implementations derive from alignment with the 8183 Single UNIX Specification: 8184 * The majority of the error conditions previously marked as extensions are now mandatory, 8185 except for the STREAMS-related error conditions. 250 Technical Standard (2000) (Draft July 28, 2000) Headers 8186 NAME 8187 fcntl.h - file control options 8188 SYNOPSIS 8189 #include 8190 DESCRIPTION 8191 The header shall define the following requests and arguments for use by the functions 8192 fcntl( ) and open( ). 8193 Values for cmd used by fcntl( ) (the following values are unique) are as follows: 8194 F_DUPFD Duplicate file descriptor. 8195 F_GETFD Get file descriptor flags. 8196 F_SETFD Set file descriptor flags. 8197 F_GETFL Get file status flags and file access modes. 8198 F_SETFL Set file status flags. 8199 F_GETLK Get record locking information. 8200 F_SETLK Set record locking information. 8201 F_SETLKW Set record locking information; wait if blocked. 8202 F_GETOWN Get process or process group ID to receive SIGURG signals. 8203 F_SETOWN Set process or process group ID to receive SIGURG signals. 8204 File descriptor flags used for fcntl( ) are as follows: 8205 FD_CLOEXEC Close the file descriptor upon execution of an exec family function. 8206 Values for l_type used for record locking with fcntl( ) (the following values are unique) are as 8207 follows: 8208 F_RDLCK Shared or read lock. 8209 F_UNLCK Unlock. 8210 F_WRLCK Exclusive or write lock. 8211 XSI The values used for l_whence, {SEEK_SET}, {SEEK_CUR}, and {SEEK_END} shall be defined as 8212 described in . 8213 The following four sets of values for oflag used by open( ) shall be bitwise-distinct: 8214 O_CREAT Create file if it does not exist. 8215 O_EXCL Exclusive use flag. 8216 O_NOCTTY Do not assign controlling terminal. 8217 O_TRUNC Truncate flag. 8218 File status flags used for open( ) and fcntl( ) are as follows: 8219 O_APPEND Set append mode. 8220 SIO O_DSYNC Write according to synchronized I/O data integrity completion. 8221 O_NONBLOCK Non-blocking mode. Base Definitions, Issue 6 251 Headers 8222 SIO O_RSYNC Synchronized read I/O operations. 8223 O_SYNC Write according to synchronized I/O file integrity completion. 8224 Mask for use with file access modes is as follows: 8225 O_ACCMODE Mask for file access modes. 8226 File access modes used for open( ) and fcntl( ) are as follows: 8227 O_RDONLY Open for reading only. 8228 O_RDWR Open for reading and writing. 8229 O_WRONLY Open for writing only. 8230 XSI The symbolic names for file modes for use as values of mode_t shall be defined as described in 8231 . 8232 ADV Values for advice used by posix_fadvise( ) are as follows: 8233 POSIX_FADV_NORMAL 8234 The application has no advice to give on its behavior with respect to the specified data. It is 8235 the default characteristic if no advice is given for an open file. 8236 POSIX_FADV_SEQUENTIAL 8237 The application expects to access the specified data sequentially from lower offsets to 8238 higher offsets. 8239 POSIX_FADV_RANDOM 8240 The application expects to access the specified data in a random order. 8241 POSIX_FADV_WILLNEED 8242 The application expects to access the specified data in the near future. 8243 POSIX_FADV_DONTNEED 8244 The application expects that it will not access the specified data in the near future. 8245 POSIX_FADV_NOREUSE 8246 The application expects to access the specified data once and then not reuse it thereafter. 8247 8248 The structure flock describes a file lock. It shall include the following members: 8249 short l_type Type of lock; F_RDLCK, F_WRLCK, F_UNLCK. 8250 short l_whence Flag for starting offset. 8251 off_t l_start Relative offset in bytes. 8252 off_t l_len Size; if 0 then until EOF. 8253 pid_t l_pid Process ID of the process holding the lock; returned with F_GETLK. 8254 The mode_t, off_t, and pid_t types shall be defined as described in . | 8255 The following shall be declared as functions and may also be defined as macros. Function 8256 prototypes shall be provided for use with an ISO C standard compiler. 8257 int creat(const char *, mode_t); 8258 int fcntl(int, int, ...); 8259 int open(const char *, int, ...); 8260 ADV int posix_fadvise(int, off_t, size_t, int); 8261 int posix_fallocate(int, off_t, size_t); 8262 252 Technical Standard (2000) (Draft July 28, 2000) Headers 8263 XSI Inclusion of the header may also make visible all symbols from and 8264 . 8265 APPLICATION USAGE 8266 None. 8267 RATIONALE 8268 None. 8269 FUTURE DIRECTIONS 8270 None. 8271 SEE ALSO 8272 , , , the System Interfaces volume of IEEE Std. 1003.1-200x, 8273 creat( ), exec( ), fcntl( ), open( ), posix_fadvise( ), posix_fallocate( ), posix_madvise( ) 8274 CHANGE HISTORY 8275 First released in Issue 1. Derived from Issue 1 of the SVID. | 8276 Issue 4 8277 A reference to is added for the definition of l_whence, {SEEK_SET}, {SEEK_CUR}, and 8278 {SEEK_END}, and marked as an extension. 8279 A reference to is added for the symbolic names of file modes used as values of 8280 mode_t, and marked as an extension. 8281 A reference to is added for the definition of mode_t, off_t, and pid_t, and marked 8282 as an extension. 8283 A warning is added indicating that inclusion of may also make visible all symbols 8284 from and . This is marked as an extension. 8285 The following change is incorporated for alignment with the ISO POSIX-1 standard: 8286 * The function declarations in this header are expanded to full ISO C standard prototypes. 8287 Issue 5 8288 The DESCRIPTION is updated for alignment with POSIX Realtime Extension. 8289 Issue 6 8290 The following changes are made for alignment with the ISO POSIX-1: 1996 standard: 8291 * O_DSYNC and O_RSYNC are marked as part of the Synchronized Input and Output option. | 8292 The following new requirements on POSIX implementations derive from alignment with the 8293 Single UNIX Specification: 8294 * The definition of the mode_t, off_t, and pid_t types is mandated. 8295 The F_GETOWN and F_SETOWN values are added for sockets. 8296 The posix_fadvise( ), posix_fallocate( ), and posix_madvise( ) functions are added for alignment with 8297 IEEE Std. 1003.1d-1999. | 8298 IEEE PASC Interpretation 1003.1 #102 is applied moving the prototype for posix_madvise( ) to || 8299 . | Base Definitions, Issue 6 253 Headers 8300 NAME | 8301 fenv.h - floating-point environment | 8302 SYNOPSIS | 8303 #include | 8304 DESCRIPTION | 8305 CX The functionality described on this reference page extends the ISO C standard. Applications | 8306 shall define the appropriate feature test macro (see the System Interfaces volume of | 8307 IEEE Std. 1003.1-200x, Section 2.2, The Compilation Environment) to enable the visibility of | 8308 symbols in this header. | 8309 The header shall define the following data types through typedef: | 8310 fenv_t Represents the entire floating-point environment. The floating-point environment | 8311 refers collectively to any floating-point status flags and control modes supported | 8312 by the implementation. | 8313 fexcept_t Represents the floating-point status flags collectively, including any status the | 8314 implementation associates with the flags. A floating-point status flag is a system | 8315 variable whose value is set (but never cleared) when a floating-point exception is | 8316 raised, which occurs as a side effect of exceptional floating-point arithmetic to | 8317 provide auxiliary information. A floating-point control mode is a system variable | 8318 whose value may be set by the user to affect the subsequent behavior of floating- | 8319 point arithmetic. | 8320 The header shall define the following constants: | 8321 FE_DIVBYZERO | 8322 FE_INEXACT | 8323 FE_INVALID | 8324 FE_OVERFLOW | 8325 FE_UNDERFLOW These constants are defined if and only if the implementation supports | 8326 the floating-point exception by means of the flaoting-point functions | 8327 fwclearexcept( ), fegetexceptflag( ), feraiseexcept( ), fesetexceptflag( ), and | 8328 fetestexcept( ). Each expands to an integer constant expression with values | 8329 such that bitwise-inclusive ORs of all combinations of the constants result | 8330 in distinct values. | 8331 FE_ALL_EXCEPT Simply the bitwise-inclusive OR of all floating-point exception constants | 8332 defined above. | 8333 FE_DOWNWARD | 8334 FE_TONEAREST | 8335 FE_TOWARDZERO | 8336 FE_UPWARD These constants are defined if and only if the implementation supports | 8337 getting and setting the represented rounding direction by means of the | 8338 fegetround( ) and fesetround( ) functions. Each expands to an integer | 8339 constant expression whose values are distinct non-negative vales. | 8340 FE_DFL_ENV Represents the floating-point environment (that is, the one installed at | 8341 program startup) and has type pointer to const-qualified fenv_t). It can | 8342 be used as an argument to the functions within the header that | 8343 manage the floating-point environment. | 8344 The following shall be declared as functions and may also be defined as macros. Function | 8345 prototypes shall be provided for use with an ISO C standard compiler. | 254 Technical Standard (2000) (Draft July 28, 2000) Headers 8346 void feclearexcept(int); | 8347 void fegetexceptflag(fexcept_t *, int); | 8348 void feraiseexcept(int); | 8349 void fesetexceptflag(const fexcept_t *, int); | 8350 int fetestexcept(int); | 8351 int fegetround(void); | 8352 int fesetround(int); | 8353 void fegetenv(fenv_t *); | 8354 int feholdexcept(fenv_t *); | 8355 void fesetenv(const fenv_t *); | 8356 void feupdateenv(const fenv_t *); | 8357 APPLICATION USAGE | 8358 This header is designed to support the floating-point exception status flags and directed- | 8359 rounding control modes required by the IEC 60559: 1989 standard, and other similar floating- | 8360 point state information. Also it is designed to facilitate code portability among all systems. | 8361 Certain application programming conventions support the intended model of use for the | 8362 floating-point environment: | 8363 * A function call does not alter its caller's floating-point control modes, clear its caller's | 8364 floating-point status flags, nor depend on the state of its caller's floating-point status flags | 8365 unless the function is so documented. | 8366 * A function call is assumed to require default floating-point control modes, unless its | 8367 documentation promises otherwise. | 8368 * A function call is assumed to have the potential for raising floating-point exceptions, unless | 8369 its documentation promises otherwise. | 8370 With these conventions, an application can safely assume default floating-point control modes | 8371 (or be unaware of them). The responsibilities associated with accessing the floating-point | 8372 environment fall on the application that does so explicitly. | 8373 Even though the rounding direction macros may expand to constants corresponding to the | 8374 values of FLT_ROUNDS, they are not required to do so. | 8375 The FENV_ACCESS pragma provides a means to inform the implementation when an | 8376 application might access the floating-point environment to test floating-point status flags or run | 8377 under non-default floating-point control modes. The pragma shall occur either outside external | 8378 declarations or preceding all explicit declarations and statements inside a compound statement. | 8379 When outside external declarations, the pragma takes effect from its occurrence until another | 8380 FENV_ACCESS pragma is encountered, or until the end of the translation unit. When inside a | 8381 compound statement, the pragma takes effect from its occurrence until another FENV_ACCESS | 8382 pragma is encountered (including within a nested compound statement), or until the end of the | 8383 compound statement; at the end of a compound statement the state for the pragma is restored to | 8384 its condition just before the compound statement. If this pragma is used in any other context, the | 8385 behavior is undefined. If part of an application tests floating-point status flags, sets floating- | 8386 point control modes, or runs under non-default mode settings, but was translated with the state | 8387 for the FENV_ACCESS pragma off, the behavior is undefined. The default state (on or off) for | 8388 the pragma is implementation-defined. (When execution passes from a part of the application | 8389 translated with FENV_ACCESS off to a part translated with FENV_ACCESS on, the state of the | 8390 floating-point status flags is unspecified and the floating-point control modes have their default | 8391 settings.) For example: | 8392 #include | 8393 void f(double x) | Base Definitions, Issue 6 255 Headers 8394 { | 8395 #pragma STDC FENV_ACCESS ON | 8396 void g(double); | 8397 void h(double); | 8398 /* ... */ | 8399 g(x + 1); | 8400 h(x + 1); | 8401 /* ... */ | 8402 } | 8403 If the function g( ) might depend on status flags set as a side effect of the first x+1, or if the | 8404 second x+1 might depend on control modes set as a side effect of the call to function g( ), then | 8405 the application shall contain an appropriately placed invocation as follows: | 8406 #pragma STDC FENV_ACCESS ON | 8407 RATIONALE | 8408 The floating-point environment as defined here includes only execution-time modes, not the | 8409 myriad of possible translation-time options that can affect an application's results. Each such | 8410 option's deviation from IEEE Std. 1003.1-200x should be well documented. | 8411 Dynamic Versus Static Modes | 8412 Dynamic modes are potentially problematic because: | 8413 1. The application may have to defend against undesirable mode settings, which impose | 8414 intellectual as well as time and space overhead. | 8415 2. The translator may not know which mode settings will be in effect or which functions | 8416 change them at execution time, which inhibits optimization. | 8417 The ISO/IEC 9899: 1999 standard addresses these problems without changing the dynamic | 8418 nature of the modes. | 8419 An alternate approach would have been to present a model of static modes with explicit | 8420 utterances to the translator about what mode settings would be in effect. This would have | 8421 avoided any uncertainty due to the global nature of dynamic modes or the dependency on | 8422 unenforced conventions. However, some essentially dynamic mechanism still would have been | 8423 needed in order to allow functions to inherit (honor) their caller's modes. The IEC 60559: 1989 | 8424 standard requires dynamic rounding direction modes. For the many architectures that maintain | 8425 these modes in control registers, implementation of the static model would be more costly. Also, | 8426 standard C has no facility, other than pragmas, for supporting static modes. | 8427 An implementation on an architecture that provides only static control of modes (for example, | 8428 through opword encodings) still could support the dynamic model, by generating multiple code | 8429 streams with tests of a private global variable containing the mode setting. Only modules under | 8430 an enabling FENV_ACCESS pragma would need such special treatment. | 8431 Translation | 8432 An implementation is not required to provide a facility for altering the modes for translation- | 8433 time arithmetic, or for making exception flags from the translation available to the executing | 8434 application. The language and library provide facilities to cause floating-point operations to be | 8435 done at execution time when they can be subjected to varying dynamic modes and their | 8436 exceptions detected. The need does not seem sufficient to require similar facilities for translation. | 256 Technical Standard (2000) (Draft July 28, 2000) Headers 8437 The fexcept_t Type | 8438 fexcept_t does not have to be an integer type. Its values must be obtained by a call to | 8439 fegetexceptflag( ), and cannot be created by logical operations from the exception macros. An | 8440 implementation might simply implement fexcept_ as an int and use the representations | 8441 reflected by the exception macros, but is not required to; other representations might contain | 8442 extra information about the exceptions. fexcept_t might be a struct with a member for each | 8443 exception (that might hold the address of the first or last floating-point instruction that caused | 8444 that exception). The ISO/IEC 9899: 1999 standard makes no claims about the internals of an | 8445 fexcept_t, and so the user cannot inspect it. | 8446 Exception and Rounding Macros | 8447 Unsupported macros are not defined in order to ensure that their use results in a translation | 8448 error. An application might explicitly define such macros to allow translation of code (perhaps | 8449 never executed) containing the macros. An unsupported exception macro should be defined to | 8450 be 0; for example: | 8451 #ifndef FE_INEXACT | 8452 #define FE_INEXACT 0 | 8453 #endif | 8454 so that a bitwise-inclusive OR of macros has a reasonable effect. | 8455 Exceptions | 8456 In previous drafts of IEEE Std. 1003.1-200x, several of the exception functions returned an int | 8457 indicating whether the excepts argument represented supported exceptions. This facility was | 8458 deemed unnecessary because: | 8459 excepts & FE_ALL_EXCEPT | 8460 can be used to test invalidity of the excepts argument. | 8461 Rounding Precision | 8462 The IEC 60559: 1989 standard floating-point standard prescribes rounding precision modes (in | 8463 addition to the rounding direction modes covered by the functions in this reference page) as a | 8464 means for systems whose results are always double or extended to mimic systems that deliver | 8465 results to narrower formats. An implementation of C can meet this goal in any of the following | 8466 ways: | 8467 1. By supporting the evaluation method indicated by FLT_EVAL_METHOD equal to 0 | 8468 2. By providing pragmas or compile options to shorten results by rounding to the | 8469 IEC 60559: 1989 standard single or double precision | 8470 3. By providing functions to dynamically set and get rounding precision modes which | 8471 shorten results by rounding to the IEC 60559: 1989 standard single or double precision; | 8472 recommended are functions fesetprec( ) and fegetprec( ) and macros FE_FLTPREC, | 8473 FE_DBLPREC, and FE_LDBLPREC, analogous to the functions and macros for the | 8474 rounding direction modes | 8475 IEEE Std. 1003.1-200x does not include a portable interface for precision control because the | 8476 IEC 60559: 1989 standard floating-point standard is ambivalent on whether it intends for | 8477 precision control to be dynamic (like the rounding direction modes) or static. Indeed, some | 8478 floating-point architectures provide control modes suitable for a dynamic mechanism, and | 8479 others rely on instructions to deliver single and double-format results suitable only for a static | Base Definitions, Issue 6 257 Headers 8480 mechanism. | 8481 FUTURE DIRECTIONS | 8482 None. | 8483 SEE ALSO | 8484 The System Interfaces volume of IEEE Std. 1003.1-200x, feclearexcept( ), fegetenv( ), | 8485 fegetexceptflag( ), fegetround( ), feholdexcept( ), feraiseexcept( ), fesetenv( ), fesetexceptflag( ), | 8486 fesetround( ), fetestexcept( ), feupdateenv( ) | 8487 CHANGE HISTORY || 8488 First released in Issue 6. Included for alignment with the ISO/IEC 9899: 1999 standard. | 258 Technical Standard (2000) (Draft July 28, 2000) Headers 8489 NAME 8490 float.h - floating types 8491 SYNOPSIS 8492 #include 8493 DESCRIPTION 8494 CX The functionality described on this reference page extends the ISO C standard. Applications 8495 shall define the appropriate feature test macro (see the System Interfaces volume of 8496 IEEE Std. 1003.1-200x, Section 2.2, The Compilation Environment) to enable the visibility of 8497 symbols in this header. 8498 The characteristics of floating types are defined in terms of a model that describes a 8499 representation of floating-point numbers and values that provide information about an 8500 implementation's floating-point arithmetic. 8501 The following parameters are used to define the model for each floating-point type: 8502 s Sign (±1). 8503 b Base or radix of exponent representation (an integer >1). 8504 e Exponent (an integer between a minimum emin and a maximum emax). 8505 p Precision (the number of base-b digits in the significand). 8506 fk Non-negative integers less than b (the significand digits). 8507 A normalized floating-point number x (f1 >0 if x 0) is defined by the following model: p 8508 x = s × be × fk × b-k, emin e emax 8509 k =1 8510 FLT_RADIX is a constant expression suitable for use in the #if preprocessing directives. All | 8511 constants except FLT_RADIX and FLT_ROUNDS have separate names for all three floating- | 8512 point types. The floating-point model representation is provided for all macro names except 8513 FLT_ROUNDS. 8514 The rounding mode for floating-point addition is characterized by the value of FLT_ROUNDS: 8515 -1 Indeterminable. 8516 0 Toward 0.0. 8517 1 To nearest. 8518 2 Toward positive infinity. 8519 3 Toward negative infinity. 8520 All other values for FLT_ROUNDS characterize implementation-defined rounding behavior. | 8521 The values of operations with floating operands and values subject to the usual arithmetic | 8522 conversions and of floating constants are evaluated to a format whose range and precision may | 8523 be greater than required by the type. The use of evaluation formats is characterized by the | 8524 implementation-defined value of FLT_EVAL_METHOD: | 8525 -1 Indeterminable. | 8526 0 Evaluate all operations and constants just to the range and precision of the type. | 8527 1 Evaluate operations and constants of type float and double to the range and precision of the | 8528 double type, evaluate long double operations and constants to the range and precision of | 8529 the long double type. | Base Definitions, Issue 6 259 Headers 8530 2 Evaluate all operations and constants to the range and precision of the long double type. | 8531 All other negative values for FLT_EVAL_METHOD characterize implementation-defined | 8532 behavior. | 8533 The macro names given in the following list are defined as expressions with values that are | 8534 equal or greater in magnitude (absolute value) to those shown, with the same sign. 260 Technical Standard (2000) (Draft July 28, 2000) Headers _____________________________________________________________________________________ Name Description Value _____________________________________________________________________________________ FLT_RADIX Radix of exponent representation, b. 2 _____________________________________________________________________________________ FLT_MANT_DIG Number of base-FLT_RADIX digits in the floating-point significand, p. DBL_MANT_DIG LDBL_MANT_DIG _____________________________________________________________________________________ Number of decimal digits, n, such that any floating-point number in the widest supported floating type with pmax radix b digits can be rounded to a floating-point number with n decimal digits and back again without change to the value. Notes to Reviewers This section with side shading will not appear in the final copy. - Ed. D3, XSH, ERN 146 requires a new equation to be inserted here. However, none of the equations in float.h match the C99 style. This needs looking at again. DECIMAL_DIG 10 _____________________________________________________________________________________ FLT_DIG Number of decimal digits, q, such that any floating-point 6 number with q decimal digits can be rounded into a floating-point number with p radix b digits and back again without change to the q decimal digits, 1 if b is a power of 10 (p-1) × log10b + 0 otherwise DBL_DIG 10 LDBL_DIG 10 _____________________________________________________________________________________ FLT_MIN_EXP Minimum negative integer such that FLT_RADIX raised to that power minus 1 is a normalized floating-point number, e min DBL_MIN_EXP LDBL_MIN_EXP _____________________________________________________________________________________ FLT_MIN_10_EXP Minimum negative integer such that 10 raised to that power -37 is in the range of normalized floating-point numbers, -1 log10bemin DBL_MIN_10_EXP -37 LDBL_MIN_10_EXP -37 _____________________________________________________________________________________ FLT_MAX_EXP Maximum integer such that FLT_RADIX raised to that power minus 1 is a representable finite floating-point number, e max DBL_MAX_EXP LDBL_MAX_EXP _____________________________________________________________________________________ Base Definitions, Issue 6 261 Headers _____________________________________________________________________________________ 8535 FLT_MAX_10_EXP Maximum integer such that 10 raised to that power is in the 37 range of representable finite floating-point numbers, log10((1 - b-p) × bemax ) DBL_MAX_10_EXP 37 LDBL_MAX_10_EXP 37 _____________________________________________________________________________________ 8536 Implementation-defined values. | 8537 The macro names given in the following list are defined as expressions with values that are | 8538 equal to or greater than those shown. _____________________________________________________________________________________ 8539 FLT_MAX Maximum representable finite floating-point number, 1E+37 ( 1 - b-p ) × bemax DBL_MAX 1E+37 LDBL_MAX 1E+37 _____________________________________________________________________________________ 8540 The macro names given in the following list are defined as expressions with values that are 8541 equal to or less than those shown. _____________________________________________________________________________________ 8542 FLT_EPSILON The difference between 1.0 and the least value greater that 1E-5 1.0 that is representable in the given floating-point type, b(1-p) DBL_EPSILON 1E-9 LDBL_EPSILON 1E-9 _____________________________________________________________________________________ FLT_MIN Minimum normalized positive floating-point number, 1E-37 b(emin -1) DBL_MIN 1E-37 LDBL_MIN 1E-37 _____________________________________________________________________________________ 8543 APPLICATION USAGE 8544 None. 8545 RATIONALE 8546 None. 8547 FUTURE DIRECTIONS 8548 None. 8549 SEE ALSO 8550 None. 8551 CHANGE HISTORY 8552 First released in Issue 4. Derived from the ISO C standard. | 8553 Issue 6 | 8554 The description of the operations with floating-point values is updated for alignment with the | 8555 ISO/IEC 9899: 1999 standard. | 262 Technical Standard (2000) (Draft July 28, 2000) Headers 8556 NAME 8557 fmtmsg.h - message display structures 8558 SYNOPSIS 8559 XSI #include 8560 8561 DESCRIPTION 8562 The header shall define the following macros, which expand to constant integral 8563 expressions: 8564 MM_HARD Source of the condition is hardware. 8565 MM_SOFT Source of the condition is software. 8566 MM_FIRM Source of the condition is firmware. 8567 MM_APPL Condition detected by application. 8568 MM_UTIL Condition detected by utility. 8569 MM_OPSYS Condition detected by operating system. 8570 MM_RECOVER Recoverable error. 8571 MM_NRECOV Non-recoverable error. 8572 MM_HALT Error causing application to halt. 8573 MM_ERROR Application has encountered a non-fatal fault. 8574 MM_WARNING Application has detected unusual non-error condition. 8575 MM_INFO Informative message. 8576 MM_NOSEV No severity level provided for the message. 8577 MM_PRINT Display message on standard error. 8578 MM_CONSOLE Display message on system console. 8579 The table below indicates the null values and identifiers for fmtmsg( ) arguments. The 8580 header shall define the macros in the Identifier column, which expand to constant 8581 expressions that expand to expressions of the type indicated in the Type column: 8582 __________________________________________________ 8583 _ Argument Type Null-Value Identifier _________________________________________________ 8584 label char * (char*)0 MM_NULLLBL 8585 severity int 0 MM_NULLSEV 8586 class long 0L MM_NULLMC 8587 text char * (char*)0 MM_NULLTXT 8588 action char * (char*)0 MM_NULLACT 8589 _ tag char * (char*)0 MM_NULLTAG _________________________________________________ 8590 The header shall also define the following macros for use as return values for 8591 fmtmsg( ): 8592 MM_OK The function succeeded. 8593 MM_NOTOK The function failed completely. 8594 MM_NOMSG The function was unable to generate a message on standard error, but 8595 otherwise succeeded. Base Definitions, Issue 6 263 Headers 8596 MM_NOCON The function was unable to generate a console message, but otherwise 8597 succeeded. 8598 The following shall be declared as a function and may also be defined as a macro. A function 8599 prototype shall be provided for use with an ISO C standard compiler. 8600 int fmtmsg(long, const char *, int, 8601 const char *, const char *, const char *); 8602 APPLICATION USAGE 8603 None. 8604 RATIONALE 8605 None. 8606 FUTURE DIRECTIONS 8607 None. 8608 SEE ALSO 8609 The System Interfaces volume of IEEE Std. 1003.1-200x, fmtmsg( ) 8610 CHANGE HISTORY 8611 First released in Issue 4, Version 2. 264 Technical Standard (2000) (Draft July 28, 2000) Headers 8612 NAME 8613 fnmatch.h - file name-matching types 8614 SYNOPSIS 8615 #include 8616 DESCRIPTION 8617 The header shall define the flags and return value used by the fnmatch( ) function. 8618 The following constants are defined: 8619 FNM_NOMATCH The string does not match the specified pattern. 8620 FNM_PATHNAME Slash in string only matches slash in pattern. 8621 FNM_PERIOD Leading period in string must be exactly matched by period in pattern. 8622 FNM_NOESCAPE Disable backslash escaping. 8623 FNM_NOSYS The implementation does not support this function. (LEGACY) | 8624 The following shall be declared as a function and may also be declared as a macro. Function 8625 prototypes shall be provided for use with an ISO C standard compiler. 8626 int fnmatch(const char *, const char *, int); 8627 APPLICATION USAGE 8628 None. 8629 RATIONALE 8630 None. 8631 FUTURE DIRECTIONS 8632 None. 8633 SEE ALSO 8634 The System Interfaces volume of IEEE Std. 1003.1-200x, fnmatch( ), the Shell and Utilities volume | 8635 of IEEE Std. 1003.1-200x | 8636 CHANGE HISTORY 8637 First released in Issue 4. Derived from the ISO POSIX-2 standard. | 8638 Issue 6 | 8639 The constant FNM_NOSYS is marked LEGACY. | Base Definitions, Issue 6 265 Headers 8640 NAME 8641 ftw.h - file tree traversal 8642 SYNOPSIS 8643 XSI #include 8644 8645 DESCRIPTION 8646 The header shall define the FTW structure that includes at least the following members: 8647 int base 8648 int level 8649 The header shall define macros for use as values of the third argument to the 8650 application-supplied function that is passed as the second argument to ftw( ) and nftw( ): 8651 FTW_F File. 8652 FTW_D Directory. 8653 FTW_DNR Directory without read permission. 8654 FTW_DP Directory with subdirectories visited. 8655 FTW_NS Unknown type; stat( ) failed. 8656 FTW_SL Symbolic link. 8657 FTW_SLN Symbolic link that names a nonexistent file. 8658 The header shall define macros for use as values of the fourth argument to nftw( ): 8659 FTW_PHYS Physical walk, does not follow symbolic links. Otherwise, nftw( ) follows 8660 links but does not walk down any path that crosses itself. 8661 FTW_MOUNT The walk does not cross a mount point. 8662 FTW_DEPTH All subdirectories are visited before the directory itself. 8663 FTW_CHDIR The walk changes to each directory before reading it. 8664 The following shall be declared as functions and may also be defined as macros. Function 8665 prototypes shall be provided for use with an ISO C standard compiler. 8666 int ftw(const char *, 8667 int (*)(const char *, const struct stat *, int), int); 8668 int nftw(const char *, int (*) 8669 (const char *, const struct stat *, int, struct FTW*), 8670 int, int); 8671 The header shall define the stat structure and the symbolic names for st_mode and the 8672 file type test macros as described in . 8673 Inclusion of the header may also make visible all symbols from . 266 Technical Standard (2000) (Draft July 28, 2000) Headers 8674 APPLICATION USAGE 8675 None. 8676 RATIONALE 8677 None. 8678 FUTURE DIRECTIONS 8679 None. 8680 SEE ALSO 8681 , the System Interfaces volume of IEEE Std. 1003.1-200x, ftw( ), nftw( ) 8682 CHANGE HISTORY 8683 First released in Issue 1. Derived from Issue 1 of the SVID. | 8684 Issue 4 8685 The function declarations in this header are expanded to full ISO C standard prototypes. 8686 A reference to is added for the definition of the stat structure, the symbolic names 8687 for st_mode, and the file type test macros. 8688 A warning is added indicating that inclusion of may also make visible all symbols from 8689 . 8690 Issue 4, Version 2 8691 The following changes are incorporated in the DESCRIPTION for X/OPEN UNIX conformance: 8692 * The FTW structure is defined. 8693 * The nftw( ) function is declared by the header and is mentioned as one of the functions to 8694 which the first list of macros applies. 8695 * FTW_SL and FTW_SLN are added to the first list of macros to handle symbolic links. 8696 * Macros for use as values of the fourth argument to nftw( ) are defined. 8697 Issue 5 8698 A description of FTW_DP is added. Base Definitions, Issue 6 267 Headers 8699 NAME 8700 glob.h - path name pattern-matching types 8701 SYNOPSIS 8702 #include 8703 DESCRIPTION 8704 The header shall define the structures and symbolic constants used by the glob( ) 8705 function. 8706 The structure type glob_t shall contain at least the following members: 8707 size_t gl_pathc Count of paths matched by pattern. 8708 char **gl_pathv Pointer to a list of matched path names. 8709 size_t gl_offs Slots to reserve at the beginning of gl_pathv. 8710 The following constants shall be provided as values for the flags argument: 8711 GLOB_APPEND Append generated path names to those previously obtained. 8712 GLOB_DOOFFS Specify how many null pointers to add to the beginning of pglob- | 8713 >gl_pathv. | 8714 GLOB_ERR Cause glob( ) to return on error. 8715 GLOB_MARK Each path name that is a directory that matches pattern has a slash 8716 appended. 8717 GLOB_NOCHECK If pattern does not match any path name, then return a list consisting of 8718 only pattern. 8719 GLOB_NOESCAPE Disable backslash escaping. 8720 GLOB_NOSORT Do not sort the path names returned. 8721 The following constants shall be defined as error return values: 8722 GLOB_ABORTED The scan was stopped because GLOB_ERR was set or (*errfunc)( ) 8723 returned non-zero. 8724 GLOB_NOMATCH The pattern does not match any existing path name, and 8725 GLOB_NOCHECK was not set in flags. 8726 GLOB_NOSPACE An attempt to allocate memory failed. 8727 GLOB_NOSYS The implementation does not support this function. 8728 The following shall be declared as functions and may also be declared as macros. Function 8729 prototypes shall be provided for use with an ISO C standard compiler. 8730 int glob(const char *restrict, int, int (*restrict)(const char *, int), 8731 glob_t *restrict); 8732 void globfree (glob_t *); 8733 The implementation may define additional macros or constants using names beginning with 8734 GLOB_. 268 Technical Standard (2000) (Draft July 28, 2000) Headers 8735 APPLICATION USAGE 8736 None. 8737 RATIONALE 8738 None. 8739 FUTURE DIRECTIONS 8740 None. 8741 SEE ALSO 8742 The System Interfaces volume of IEEE Std. 1003.1-200x, glob( ), the Shell and Utilities volume of | 8743 IEEE Std. 1003.1-200x | 8744 CHANGE HISTORY 8745 First released in Issue 4. Derived from the ISO POSIX-2 standard. | 8746 Issue 6 | 8747 The restrict keyword is added to the prototype for glob( ). | Base Definitions, Issue 6 269 Headers 8748 NAME 8749 grp.h - group structure 8750 SYNOPSIS 8751 #include 8752 DESCRIPTION 8753 The header shall declare the structure group which shall include the following 8754 members: 8755 char *gr_name The name of the group. 8756 gid_t gr_gid Numerical group ID. 8757 char **gr_mem Pointer to a null-terminated array of character 8758 pointers to member names. 8759 The gid_t type shall be defined as described in . | 8760 The following shall be declared as functions and may also be defined as macros. Function 8761 prototypes shall be provided for use with an ISO C standard compiler. 8762 struct group *getgrgid(gid_t); 8763 struct group *getgrnam(const char *); 8764 TSF int getgrgid_r(gid_t, struct group *, char *, 8765 size_t, struct group **); 8766 int getgrnam_r(const char *, struct group *, char *, 8767 size_t , struct group **); 8768 XSI struct group *getgrent(void); 8769 void endgrent(void); 8770 void setgrent(void); 8771 8772 APPLICATION USAGE 8773 None. 8774 RATIONALE 8775 None. 8776 FUTURE DIRECTIONS 8777 None. 8778 SEE ALSO 8779 , the System Interfaces volume of IEEE Std. 1003.1-200x, endgrent( ), getgrgid( ), 8780 getgrnam( ) 8781 CHANGE HISTORY 8782 First released in Issue 1. 8783 Issue 4 8784 A reference to is added for the definition of gid_t and marked as an extension. 8785 The following change is incorporated for alignment with the ISO POSIX-1 standard: 8786 * The function declarations in this header are expanded to full ISO C standard prototypes. 8787 Issue 4, Version 2 8788 For X/OPEN UNIX conformance, the getgrent( ), endgrent( ), and setgrent( ) functions are added 8789 to the list of functions declared in this header. 270 Technical Standard (2000) (Draft July 28, 2000) Headers 8790 Issue 5 8791 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 8792 Issue 6 8793 The following new requirements on POSIX implementations derive from alignment with the 8794 Single UNIX Specification: 8795 * The definition of gid_t is mandated. 8796 * The getgrgid_r( ) and getgrnam_r( ) functions are marked as part of the Thread-Safe Functions | 8797 option. | Base Definitions, Issue 6 271 Headers 8798 NAME 8799 iconv.h - codeset conversion facility 8800 SYNOPSIS 8801 XSI #include 8802 8803 DESCRIPTION 8804 The header shall define the following data type through typedef: 8805 iconv_t Identifies the conversion from one codeset to another. 8806 The following shall be declared as functions and may also be declared as macros. Function 8807 prototypes shall be provided for use with an ISO C standard compiler. 8808 iconv_t iconv_open(const char *, const char *); 8809 size_t iconv(iconv_t, char **restrict, size_t *restrict, char **restrict, 8810 size_t *restrict); 8811 int iconv_close(iconv_t); 8812 APPLICATION USAGE 8813 None. 8814 RATIONALE 8815 None. 8816 FUTURE DIRECTIONS 8817 None. 8818 SEE ALSO 8819 The System Interfaces volume of IEEE Std. 1003.1-200x, iconv( ), iconv_close( ), iconv_open( ) 8820 CHANGE HISTORY 8821 First released in Issue 4. | 8822 Issue 6 | 8823 The restrict keyword is added to the prototype for iconv( ). | 272 Technical Standard (2000) (Draft July 28, 2000) Headers 8824 NAME 8825 inttypes.h - fixed size integer types | 8826 SYNOPSIS 8827 XSI #include 8828 8829 DESCRIPTION 8830 The header shall include the header. | 8831 Notes to Reviewers | 8832 This section with side shading will not appear in the final copy. - Ed. | 8833 Reviewers are asked to propose changes to eliminate duplication between inttypes.h and | 8834 stdin.h. | 8835 The header shall include definitions of at least the following types: | 8836 imaxdiv_t Structure type that is the type of the value returned by the imaxdiv( ) function. | 8837 int8_t 8-bit signed integer type. | 8838 int16_t 16-bit signed integer type. | 8839 int32_t 32-bit signed integer type. | 8840 uint8_t 8-bit unsigned integer type. | 8841 uint16_t 16-bit unsigned integer type. | 8842 uint32_t 32-bit unsigned integer type. | 8843 intptr_t Signed integer type large enough to hold any pointer. | 8844 uintptr_t Unsigned integer type large enough to hold any pointer. | 8845 If any of the following are true: 8846 * The implementation supports the _POSIX_V6_ILP32_OFFBIG programming environment | 8847 and the application is being built in the _POSIX_V6_ILP32_OFFBIG programming | 8848 environment (see the Shell and Utilities volume of IEEE Std. 1003.1-200x, c99, Programming | 8849 Environments). 8850 * The implementation supports the _POSIX_V6_LP64_OFF64 programming environment and | 8851 the application is being built in the _POSIX_V6_LP64_OFF64 programming environment. | 8852 * The implementation supports the _POSIX_V6_LPBIG_OFFBIG programming environment | 8853 and the application is being built in the _POSIX_V6_LPBIG_OFFBIG programming | 8854 environment. | 8855 then also shall include definitions for the following types: | 8856 int64_t 64-bit signed integer type. | 8857 uint64_t 64-bit unsigned integer type. | 8858 If _ _STDC_FORMAT_MACROS is defined before is included, then the following | 8859 object-like macros shall be defined. Each expands to a character string literal containing a | 8860 conversion specifier, possibly modified by a length modifier, suitable for use within the format | 8861 argument of a formatted input/output function when converting the corresponding integer | 8862 type. These macro names have the general form of PRI (character string literals for the fprintf( ) | 8863 and fwprintf( ) family of functions) or SCN (character string literals for the fscanf( ) and fwscanf( ) | Base Definitions, Issue 6 273 Headers 8864 family of functions), followed by the conversion specifier, followed by a name corresponding to | 8865 a similar type name in . In these names, N represents the width of the type as | 8866 described in stdint.h( ). For example, PRIdFAST32 can be used in a format string to print the | 8867 value of an integer of type int_fast32_t. | 8868 The fprintf( ) macros for signed integers are: | 8869 PRIdN PRIdLEASTN PRIdFASTN PRIdMAX PRIdPTR | 8870 PRIiN PRIiLEASTN PRIiFASTN PRIiMAX PRIiPTR | 8871 The fprintf( ) macros for unsigned integers are: | 8872 PRIoN PRIoLEASTN PRIoFASTN PRIoMAX PRIoPTR | 8873 PRIuN PRIuLEASTN PRIuFASTN PRIuMAX PRIuPTR | 8874 PRIxN PRIxLEASTN PRIxFASTN PRIxMAX PRIxPTR | 8875 PRIXN PRIXLEASTN PRIXFASTN PRIXMAX PRIXPTR | 8876 The fscanf( ) macros for signed integers are: | 8877 SCNdN SCNdLEASTN SCNdFASTN SCNdMAX SCNdPTR | 8878 SCNiN SCNiLEASTN SCNiFASTN SCNiMAX SCNiPTR | 8879 The fscanf( ) macros for unsigned integers are: | 8880 SCNoN SCNoLEASTN SCNoFASTN SCNoMAX SCNoPTR | 8881 SCNuN SCNuLEASTN SCNuFASTN SCNuMAX SCNuPTR | 8882 SCNxN SCNxLEASTN SCNxFASTN SCNxMAX SCNxPTR | 8883 For each type that the implementation provides in , the corresponding fprintf( ) | 8884 macros shall be defined and the corresponding fscanf( ) macros shall be defined unless the | 8885 implementation does not have a suitable fscanf length modifier for the type. | 8886 The following shall be declared as functions and may also be defined as macros. Function | 8887 prototypes shall be provided for use with an ISO C standard compiler. | 8888 intmax_t imaxabs(intmax_t); | 8889 imaxdiv_t imaxdiv(intmax_t, intmax_t); | 8890 intmax_t strtoimax(const char *restrict, char **restrict, int); | 8891 uintmax_t strtoumax(const char *restrict, char **restrict, int); | 8892 intmax_t wcstoimax(const wchar_t *restrict, wchar_t **restrict, int); | 8893 uintmax_t wcstoumax(const wchar_t *restrict, wchar_t **restrict, int); | 8894 EXAMPLES | 8895 #include | 8896 #include | 8897 int main(void) | 8898 { | 8899 uintmax_t i = UINTMAX_MAX; // This type always exists. | 8900 wprintf(L"The largest integer value is %020" | 8901 PRIxMAX "\n", i); | 8902 return 0; | 8903 } | 274 Technical Standard (2000) (Draft July 28, 2000) Headers 8904 APPLICATION USAGE | 8905 None. 8906 RATIONALE 8907 The header was derived from the header of the same name found on several | 8908 existing 64-bit systems. The C Standard Committee debated other methods for specifying | 8909 integer sizes and other characteristics, but in the end decided to standardize existing practice | 8910 rather than innovate in this area. | 8911 The ISO/IEC 9899: 1990 standard specifies that the language should support four signed and | 8912 unsigned integer data types-char, short, int, and long-but places very little requirement on | 8913 their size other than that int and short be at least 16 bits and long be at least as long as int and | 8914 not smaller than 32 bits. For 16-bit systems, most implementations assign 8, 16, 16, and 32 bits to | 8915 char, short, int, and long, respectively. For 32-bit systems, the common practice is to assign 8, 16, | 8916 32, and 32 bits to these types. This difference in int size can create some problems for users who | 8917 migrate from one system to another which assigns different sizes to integer types, because the | 8918 ISO C standard integer promotion rule can produce silent changes unexpectedly. The need for | 8919 defining an extended integer type increased with the introduction of 64-bit systems. | 8920 The purpose of is to provide a set of integer types whose definitions are consistent | 8921 across machines and independent of operating systems and other implementation | 8922 idiosyncrasies. It defines, via typedef, integer types of various sizes. Implementations are free to | 8923 typedef them as ISO C standard integer types or extensions that they support. Consistent use of | 8924 this header will greatly increase the portability of a users program across platforms. | 8925 FUTURE DIRECTIONS 8926 Macro names beginning with PRI or SCN followed by any lowercase letter or 'X' may be added | 8927 to the macros defined in the header. | 8928 SEE ALSO 8929 The System Interfaces volume of IEEE Std. 1003.1-200x, imaxdiv( ) | 8930 CHANGE HISTORY 8931 First released in Issue 5. 8932 Issue 6 8933 The Open Group Base Resolution bwg97-006 is applied. | 8934 This reference page is updated to align with the ISO/IEC 9899: 1999 standard. | Base Definitions, Issue 6 275 Headers 8935 NAME 8936 iso646.h - alternative spellings 8937 SYNOPSIS 8938 #include 8939 DESCRIPTION 8940 CX The functionality described on this reference page extends the ISO C standard. Applications 8941 shall define the appropriate feature test macro (see the System Interfaces volume of 8942 IEEE Std. 1003.1-200x, Section 2.2, The Compilation Environment) to enable the visibility of 8943 symbols in this header. 8944 The header shall define the following eleven macros (on the left) that expand to the 8945 corresponding tokens (on the right): 8946 and && 8947 and_eq &= 8948 bitand & 8949 bitor | 8950 compl ~ 8951 not ! 8952 not_eq != 8953 or || 8954 or_eq |= 8955 xor ^ 8956 xor_eq ^= 8957 APPLICATION USAGE 8958 None. 8959 RATIONALE 8960 None. 8961 FUTURE DIRECTIONS 8962 None. 8963 SEE ALSO 8964 None. 8965 CHANGE HISTORY 8966 First released in Issue 5. Derived from ISO/IEC 9899: 1990/Amendment 1: 1995 (E). | 276 Technical Standard (2000) (Draft July 28, 2000) Headers 8967 NAME 8968 langinfo.h - language information constants 8969 SYNOPSIS 8970 XSI #include 8971 8972 DESCRIPTION 8973 The header contains the constants used to identify items of langinfo data (see 8974 nl_langinfo ( )). The type of the constant, nl_item, shall be defined as described in . 8975 The following constants shall be defined. The entries under Category indicate in which 8976 setlocale( ) category each item is defined. 8977 ______________________________________________________________________________________ 8978 _ Constant Category Meaning _____________________________________________________________________________________ 8979 CODESET LC_CTYPE Codeset name. 8980 D_T_FMT LC_TIME String for formatting date and time. 8981 D_FMT LC_TIME Date format string. 8982 T_FMT LC_TIME Time format string. 8983 T_FMT_AMPM LC_TIME a.m. or p.m. time format string. 8984 AM_STR LC_TIME Ante Meridian affix. 8985 PM_STR LC_TIME Post Meridian affix. 8986 DAY_1 LC_TIME Name of the first day of the week (for example, Sunday). 8987 DAY_2 LC_TIME Name of the second day of the week (for example, Monday). 8988 DAY_3 LC_TIME Name of the third day of the week (for example, Tuesday). 8989 DAY_4 LC_TIME Name of the fourth day of the week 8990 (for example, Wednesday). 8991 DAY_5 LC_TIME Name of the fifth day of the week (for example, Thursday). 8992 DAY_6 LC_TIME Name of the sixth day of the week (for example, Friday). 8993 DAY_7 LC_TIME Name of the seventh day of the week 8994 (for example, Saturday). 8995 ABDAY_1 LC_TIME Abbreviated name of the first day of the week. 8996 ABDAY_2 LC_TIME Abbreviated name of the second day of the week. 8997 ABDAY_3 LC_TIME Abbreviated name of the third day of the week. 8998 ABDAY_4 LC_TIME Abbreviated name of the fourth day of the week. 8999 ABDAY_5 LC_TIME Abbreviated name of the fifth day of the week. 9000 ABDAY_6 LC_TIME Abbreviated name of the sixth day of the week. 9001 ABDAY_7 LC_TIME Abbreviated name of the seventh day of the week. 9002 MON_1 LC_TIME Name of the first month of the year. 9003 MON_2 LC_TIME Name of the second month. 9004 MON_3 LC_TIME Name of the third month. 9005 MON_4 LC_TIME Name of the fourth month. 9006 MON_5 LC_TIME Name of the fifth month. 9007 MON_6 LC_TIME Name of the sixth month. 9008 MON_7 LC_TIME Name of the seventh month. 9009 MON_8 LC_TIME Name of the eighth month. 9010 MON_9 LC_TIME Name of the ninth month. 9011 MON_10 LC_TIME Name of the tenth month. 9012 MON_11 LC_TIME Name of the eleventh month. 9013 _ MON_12 LC_TIME Name of the twelfth month. _____________________________________________________________________________________ Base Definitions, Issue 6 277 Headers 9014 ______________________________________________________________________________________ 9015 _ Constant Category Meaning _____________________________________________________________________________________ 9016 ABMON_1 LC_TIME Abbreviated name of the first month. 9017 ABMON_2 LC_TIME Abbreviated name of the second month. 9018 ABMON_3 LC_TIME Abbreviated name of the third month. 9019 ABMON_4 LC_TIME Abbreviated name of the fourth month. 9020 ABMON_5 LC_TIME Abbreviated name of the fifth month. 9021 ABMON_6 LC_TIME Abbreviated name of the sixth month. 9022 ABMON_7 LC_TIME Abbreviated name of the seventh month. 9023 ABMON_8 LC_TIME Abbreviated name of the eighth month. 9024 ABMON_9 LC_TIME Abbreviated name of the ninth month. 9025 ABMON_10 LC_TIME Abbreviated name of the tenth month. 9026 ABMON_11 LC_TIME Abbreviated name of the eleventh month. 9027 ABMON_12 LC_TIME Abbreviated name of the twelfth month. 9028 ERA LC_TIME Era description segments. 9029 ERA_D_FMT LC_TIME Era date format string. 9030 ERA_D_T_FMT LC_TIME Era date and time format string. 9031 ERA_T_FMT LC_TIME Era time format string. 9032 ALT_DIGITS LC_TIME Alternative symbols for digits. 9033 RADIXCHAR LC_NUMERIC Radix character. 9034 THOUSEP LC_NUMERIC Separator for thousands. 9035 YESEXPR LC_MESSAGES Affirmative response expression. 9036 NOEXPR LC_MESSAGES Negative response expression. 9037 CRNCYSTR LC_MONETARY Currency symbol, preceded by '-' if the symbol should 9038 appear before the value, '+' if the symbol should appear 9039 after the value, or '.' if the symbol should replace the 9040 radix character. _ _____________________________________________________________________________________ 9041 If the locale's value for p_cs_precedes and n_cs_precedes does not match, the value of 9042 nl_langinfo(CRNCYSTR) is unspecified. 9043 The following shall be declared as a function and may also be declared as a macro. Function 9044 prototypes shall be provided for use with an ISO C standard compiler. 9045 char *nl_langinfo(nl_item); 9046 Inclusion of the header may also make visible all symbols from . 9047 APPLICATION USAGE 9048 Wherever possible, users are advised to use functions compatible with those in the ISO C 9049 standard to access items of langinfo data. In particular, the strftime( ) function should be used to 9050 access date and time information defined in category LC_TIME. The localeconv( ) function 9051 should be used to access information corresponding to RADIXCHAR, THOUSEP, and 9052 CRNCYSTR. 9053 RATIONALE 9054 None. 9055 FUTURE DIRECTIONS 9056 None. 9057 SEE ALSO 9058 The System Interfaces volume of IEEE Std. 1003.1-200x, nl_langinfo ( ), localeconv( ), strfmon( ), 9059 strftime( ), Chapter 7 (on page 143) 278 Technical Standard (2000) (Draft July 28, 2000) Headers 9060 CHANGE HISTORY 9061 First released in Issue 2. 9062 Issue 4 9063 The function declarations in this header are expanded to full ISO C standard prototypes. 9064 The constants CODESET, T_FMT_AMPM, ERA, ERA_D_FMT, ALT_DIGITS, YESEXPR, and 9065 NOEXPR are added. 9066 The constants YESSTR and NOSTR are marked TO BE WITHDRAWN. 9067 Reference to the Gregorian calendar is removed. 9068 The constants YESSTR and NOSTR are now defined as belonging to category LC_MESSAGES. 9069 Previously they were defined as constants in category LC_ALL. 9070 A warning is added indicating that inclusion of may also make visible all symbols 9071 from . 9072 The APPLICATION USAGE section is expanded to recommend use of the localeconv( ) function. 9073 Issue 5 9074 The constants YESSTR and NOSTR are marked LEGACY. 9075 Issue 6 9076 The constants YESSTR and NOSTR are removed. Base Definitions, Issue 6 279 Headers 9077 NAME 9078 libgen.h - definitions for pattern matching functions 9079 SYNOPSIS 9080 XSI #include 9081 9082 DESCRIPTION 9083 The following shall be declared as functions and may also be defined as macros. Function 9084 prototypes shall be provided for use with an ISO C standard compiler. 9085 char *basename(char *); 9086 char *dirname(char *); 9087 APPLICATION USAGE 9088 None. 9089 RATIONALE 9090 None. 9091 FUTURE DIRECTIONS 9092 None. 9093 SEE ALSO 9094 The System Interfaces volume of IEEE Std. 1003.1-200x, basename( ), dirname( ) 9095 CHANGE HISTORY 9096 First released in Issue 4, Version 2. 9097 Issue 5 9098 The function prototypes for basename( ) and dirname( ) are changed to indicate that the first 9099 argument is of type char* rather than const char*. 280 Technical Standard (2000) (Draft July 28, 2000) Headers 9100 NAME 9101 limits.h - implementation-defined constants | 9102 SYNOPSIS 9103 #include 9104 DESCRIPTION 9105 CX The functionality described on this reference page extends the ISO C standard. Applications 9106 shall define the appropriate feature test macro (see the System Interfaces volume of 9107 IEEE Std. 1003.1-200x, Section 2.2, The Compilation Environment) to enable the visibility of 9108 symbols in this header. 9109 The header shall define various symbolic names. Different categories of names are 9110 described below. 9111 The names represent various limits on resources that the implementation imposes on | 9112 applications. | 9113 Implementations may choose any appropriate value for each limit, provided it is not more 9114 restrictive than the Minimum Acceptable Values listed below. Symbolic constant names 9115 beginning with _POSIX may be found in . 9116 Applications should not assume any particular value for a limit. To achieve maximum 9117 portability, an application should not require more resource than the Minimum Acceptable 9118 Value quantity. However, an application wishing to avail itself of the full amount of a resource 9119 available on an implementation may make use of the value given in on that | 9120 particular implementation, by using the symbolic names listed below. It should be noted, | 9121 however, that many of the listed limits are not invariant, and at runtime, the value of the limit | 9122 may differ from those given in this header, for the following reasons: | 9123 * The limit is path name-dependent. 9124 * The limit differs between the compile and runtime machines. 9125 For these reasons, an application may use the fpathconf( ), pathconf( ), and sysconf( ) functions to 9126 determine the actual value of a limit at runtime. 9127 The items in the list ending in _MIN give the most negative values that the mathematical types 9128 are guaranteed to be capable of representing. Numbers of a more negative value may be | 9129 supported on some implementations, as indicated by the header on the | 9130 implementation, but applications requiring such numbers are not guaranteed to be portable to | 9131 all implementations. For positive constants ending in _MIN, this indicates the minimum | 9132 acceptable value. | 9133 The Minimum Acceptable Value symbol '*' indicates that there is no guaranteed value across 9134 all conforming implementations. | 9135 Runtime Invariant Values (Possibly Indeterminate) 9136 A definition of one of the symbolic names in the following list shall be omitted from 9137 on specific implementations where the corresponding value is equal to or greater than the stated 9138 minimum, but is indeterminate. 9139 This indetermination might depend on the amount of available memory space on a specific | 9140 instance of a specific implementation. The actual value supported by a specific instance shall be | 9141 provided by the sysconf( ) function. | 9142 AIO {AIO_LISTIO_MAX} 9143 Maximum number of I/O operations in a single list I/O call supported by the Base Definitions, Issue 6 281 Headers 9144 implementation. 9145 Minimum Acceptable Value: {_POSIX_AIO_LISTIO_MAX} 9146 AIO {AIO_MAX} 9147 Maximum number of outstanding asynchronous I/O operations supported by the 9148 implementation. 9149 Minimum Acceptable Value: {_POSIX_AIO_MAX} 9150 AIO {AIO_PRIO_DELTA_MAX} 9151 The maximum amount by which a process can decrease its asynchronous I/O priority level 9152 from its own scheduling priority. 9153 Minimum Acceptable Value: 0 9154 {ARG_MAX} 9155 Maximum length of argument to the exec functions including environment data. 9156 Minimum Acceptable Value: {_POSIX_ARG_MAX} 9157 XSI {ATEXIT_MAX} 9158 Maximum number of functions that may be registered with atexit( ). 9159 Minimum Acceptable Value: 32 9160 {CHILD_MAX} 9161 Maximum number of simultaneous processes per real user ID. 9162 Minimum Acceptable Value: 25 9163 TMR {DELAYTIMER_MAX} 9164 Maximum number of timer expiration overruns. 9165 Minimum Acceptable Value: {_POSIX_DELAYTIMER_MAX} 9166 XSI {IOV_MAX} 9167 Maximum number of iovec structures that one process has available for use with readv( ) or 9168 writev( ). 9169 Minimum Acceptable Value: {_XOPEN_IOV_MAX} 9170 {LOGIN_NAME_MAX} 9171 Maximum length of a login name. 9172 Minimum Acceptable Value: {_POSIX_LOGIN_NAME_MAX} 9173 MSG {MQ_OPEN_MAX} 9174 The maximum number of open message queue descriptors a process may hold. 9175 Minimum Acceptable Value: {_POSIX_MQ_OPEN_MAX} 9176 MSG {MQ_PRIO_MAX} 9177 The maximum number of message priorities supported by the implementation. 9178 Minimum Acceptable Value: {_POSIX_MQ_PRIO_MAX} 9179 {OPEN_MAX} 9180 Maximum number of files that one process can have open at any one time. 9181 Minimum Acceptable Value: 20 9182 {PAGESIZE} 9183 Size in bytes of a page. 9184 Minimum Acceptable Value: 1 9185 XSI {PAGE_SIZE} 9186 Same as {PAGESIZE}. If either {PAGESIZE} or {PAGE_SIZE} is defined, the other is defined 9187 with the same value. | 282 Technical Standard (2000) (Draft July 28, 2000) Headers 9188 THR {PTHREAD_DESTRUCTOR_ITERATIONS} | 9189 Maximum number of attempts made to destroy a thread's thread-specific data values on 9190 thread exit. 9191 Minimum Acceptable Value: {_POSIX_THREAD_DESTRUCTOR_ITERATIONS} | 9192 THR {PTHREAD_KEYS_MAX} | 9193 Maximum number of data keys that can be created by a process. 9194 Minimum Acceptable Value: {_POSIX_THREAD_KEYS_MAX} | 9195 THR {PTHREAD_STACK_MIN} | 9196 Minimum size in bytes of thread stack storage. 9197 Minimum Acceptable Value: 0 | 9198 THR {PTHREAD_THREADS_MAX} | 9199 Maximum number of threads that can be created per process. 9200 Minimum Acceptable Value: {_POSIX_THREAD_THREADS_MAX} | 9201 {RE_DUP_MAX} 9202 The number of repeated occurrences of a BRE permitted by the regexec( ) and regcomp( ) 9203 functions when using the interval notation {\(m,n\}; see Section 9.3.6 (on page 201). 9204 Minimum Acceptable Value: {_POSIX2_RE_DUP_MAX} 9205 RTS {RTSIG_MAX} 9206 Maximum number of realtime signals reserved for application use in this implementation. 9207 Minimum Acceptable Value: {_POSIX_RTSIG_MAX} 9208 SEM {SEM_NSEMS_MAX} 9209 Maximum number of semaphores that a process may have. 9210 Minimum Acceptable Value: {_POSIX_SEM_NSEMS_MAX} 9211 SEM {SEM_VALUE_MAX} 9212 The maximum value a semaphore may have. 9213 Minimum Acceptable Value: {_POSIX_SEM_VALUE_MAX} 9214 RTS {SIGQUEUE_MAX} 9215 Maximum number of queued signals that a process may send and have pending at the 9216 receiver(s) at any time. 9217 Minimum Acceptable Value: {_POSIX_SIGQUEUE_MAX} 9218 SS|TSP {SS_REPL_MAX} 9219 The maximum number of replenishment operations that may be simultaneously pending 9220 for a particular sporadic server scheduler. 9221 Minimum Acceptable Value: {_POSIX_SS_REPL_MAX} 9222 {STREAM_MAX} 9223 The number of streams that one process can have open at one time. If defined, it has the 9224 same value as {FOPEN_MAX} (see ). 9225 Minimum Acceptable Value: {_POSIX_STREAM_MAX} 9226 {SYMLOOP_MAX} 9227 Maximum number of symbolic links that can be reliably traversed in the resolution of a 9228 path name in the absence of a loop. 9229 Minimum Acceptable Value: {_POSIX_SYMLOOP_MAX} 9230 TMR {TIMER_MAX} 9231 Maximum number of timers per-process supported by the implementation. 9232 Minimum Acceptable Value: {_POSIX_TIMER_MAX} | Base Definitions, Issue 6 283 Headers 9233 TRC {TRACE_EVENT_NAME_MAX} | 9234 Maximum length of the trace event name. | 9235 Minimum Acceptable Value: {_POSIX_TRACE_EVENT_NAME_MAX} | 9236 TRC {TRACE_NAME_MAX} | 9237 Maximum length of the trace generation version string or of the trace stream name. | 9238 Minimum Acceptable Value: {_POSIX_TRACE_NAME_MAX} | 9239 TRC {TRACE_SYS_MAX} | 9240 Maximum number of trace streams that may simultaneously exist in the system. | 9241 Minimum Acceptable Value: {_POSIX_TRACE_SYS_MAX} | 9242 TRC {TRACE_USER_EVENT_MAX} | 9243 Maximum number of user trace event type identifiers that may simultaneously exist in a | 9244 traced process, including the predefined user trace event | 9245 POSIX_TRACE_UNNAMED_USER_EVENT. | 9246 Minimum Acceptable Value: {_POSIX_TRACE_USER_EVENT_MAX} | 9247 {TTY_NAME_MAX} 9248 Maximum length of terminal device name. 9249 Minimum Acceptable Value: {_POSIX_TTY_NAME_MAX} 9250 {TZNAME_MAX} 9251 Maximum number of bytes supported for the name of a timezone (not of the TZ variable). 9252 Minimum Acceptable Value: {_POSIX_TZNAME_MAX} 9253 Note: The length given by {TZNAME_MAX} does not include the quoting characters 9254 mentioned in Section 8.3 (on page 192). 9255 Path Name Variable Values 9256 The values in the following list may be constants within an implementation or may vary from 9257 one path name to another. For example, file systems or directories may have different 9258 characteristics. 9259 A definition of one of the values shall be omitted from the header on specific 9260 implementations where the corresponding value is equal to or greater than the stated minimum, 9261 but where the value can vary depending on the file to which it is applied. The actual value 9262 supported for a specific path name shall be provided by the pathconf( ) function. 9263 {FILESIZEBITS} | 9264 Minimum number of bits needed to represent, as a signed integer value, the maximum size 9265 of a regular file allowed in the specified directory. 9266 Minimum Acceptable Value: 32 | 9267 {LINK_MAX} 9268 Maximum number of links to a single file. 9269 Minimum Acceptable Value: {_POSIX_LINK_MAX} 9270 {MAX_CANON} 9271 Maximum number of bytes in a terminal canonical input line. 9272 Minimum Acceptable Value: {_POSIX_MAX_CANON} 9273 {MAX_INPUT} 9274 Minimum number of bytes for which space is available in a terminal input queue; therefore, 9275 the maximum number of bytes a portable application may require to be typed as input 9276 before reading them. 9277 Minimum Acceptable Value: {_POSIX_MAX_INPUT} 284 Technical Standard (2000) (Draft July 28, 2000) Headers 9278 {NAME_MAX} 9279 Maximum number of bytes in a file name (not including terminating null). 9280 Minimum Acceptable Value: {_POSIX_NAME_MAX} 9281 {PATH_MAX} 9282 Maximum number of bytes in a path name, including the terminating null character. 9283 Minimum Acceptable Value: {_POSIX_PATH_MAX} 9284 {PIPE_BUF} 9285 Maximum number of bytes that is guaranteed to be atomic when writing to a pipe. 9286 Minimum Acceptable Value: {_POSIX_PIPE_BUF} 9287 ADV {POSIX_ALLOC_SIZE_MIN} 9288 Minimum number of bytes of storage actually allocated for any portion of a file. 9289 Minimum Acceptable Value: Not specified. 9290 ADV {POSIX_REC_INCR_XFER_SIZE} 9291 Recommended increment for file transfer sizes between the 9292 {POSIX_REC_MIN_XFER_SIZE} and {POSIX_REC_MAX_XFER_SIZE} values. 9293 Minimum Acceptable Value: Not specified. 9294 ADV {POSIX_REC_MAX_XFER_SIZE} 9295 Maximum recommended file transfer size. 9296 Minimum Acceptable Value: Not specified. 9297 ADV {POSIX_REC_MIN_XFER_SIZE} 9298 Minimum recommended file transfer size. 9299 Minimum Acceptable Value: Not specified. 9300 ADV {POSIX_REC_XFER_ALIGN} 9301 Recommended file transfer buffer alignment. 9302 Minimum Acceptable Value: Not specified. 9303 {SYMLINK_MAX} 9304 Maximum number of bytes in a symbolic link. 9305 Minimum Acceptable Value: {_POSIX_SYMLINK_MAX} 9306 Runtime Increasable Values 9307 The magnitude limitations in the following list shall be fixed by specific implementations. An 9308 application should assume that the value supplied by in a specific implementation is 9309 the minimum that pertains whenever the application is run under that implementation. A 9310 specific instance of a specific implementation may increase the value relative to that supplied by 9311 for that implementation. The actual value supported by a specific instance shall be 9312 provided by the sysconf( ) function. 9313 {BC_BASE_MAX} 9314 Maximum obase values allowed by the bc utility. 9315 Minimum Acceptable Value: {_POSIX2_BC_BASE_MAX} 9316 {BC_DIM_MAX} 9317 Maximum number of elements permitted in an array by the bc utility. 9318 Minimum Acceptable Value: {_POSIX2_BC_DIM_MAX} 9319 {BC_SCALE_MAX} 9320 Maximum scale value allowed by the bc utility. 9321 Minimum Acceptable Value: {_POSIX2_BC_SCALE_MAX} Base Definitions, Issue 6 285 Headers 9322 {BC_STRING_MAX} 9323 Maximum length of a string constant accepted by the bc utility. 9324 Minimum Acceptable Value: {_POSIX2_BC_STRING_MAX} 9325 {CHARCLASS_NAME_MAX} 9326 Maximum number of bytes in a character class name. 9327 Minimum Acceptable Value: {_POSIX2_CHARCLASS_NAME_MAX} 9328 {COLL_WEIGHTS_MAX} 9329 Maximum number of weights that can be assigned to an entry of the LC_COLLATE order 9330 keyword in the locale definition file; see Chapter 7 (on page 143). 9331 Minimum Acceptable Value: {_POSIX2_COLL_WEIGHTS_MAX} 9332 {EXPR_NEST_MAX} 9333 Maximum number of expressions that can be nested within parentheses by the expr utility. 9334 Minimum Acceptable Value: {_POSIX2_EXPR_NEST_MAX} 9335 {LINE_MAX} 9336 Unless otherwise noted, the maximum length, in bytes, of a utility's input line (either 9337 standard input or another file), when the utility is described as processing text files. The 9338 length includes room for the trailing newline. 9339 Minimum Acceptable Value: {_POSIX2_LINE_MAX} 9340 {NGROUPS_MAX} 9341 Maximum number of simultaneous supplementary group IDs per process. 9342 Minimum Acceptable Value: 8 9343 {RE_DUP_MAX} 9344 Maximum number of repeated occurrences of a regular expression permitted when using 9345 the interval notation \{m,n\}; see Chapter 9 (on page 195). 9346 Minimum Acceptable Value: {_POSIX2_RE_DUP_MAX} 9347 Maximum Values 9348 TMR The symbolic constants in the following list shall be defined in with the values 9349 shown. These are symbolic names for the most restrictive value for certain features on an | 9350 implementation supporting the Timers option. A conforming implementation shall provide | 9351 values no larger than these values. A portable application must not require a smaller value for | 9352 correct operation. | 9353 TMR {_POSIX_CLOCKRES_MIN} 9354 The resolution of the CLOCK_REALTIME clock, in nanoseconds. 9355 Value: 20 000 000 | 9356 MON If the Monotonic Clock option is supported, the resolution of the CLOCK_MONOTONIC 9357 clock, in nanoseconds, is represented by {_POSIX_CLOCKRES_MIN}. 9358 Minimum Values 9359 The symbolic constants in the following list shall be defined in with the values 9360 shown. These are symbolic names for the most restrictive value for certain features on an | 9361 implementation conforming to this volume of IEEE Std. 1003.1-200x. Related symbolic constants | 9362 are defined elsewhere in this volume of IEEE Std. 1003.1-200x which reflect the actual | 9363 implementation and which need not be as restrictive. A conforming implementation shall 9364 provide values at least this large. A strictly conforming application must not require a larger 9365 value for correct operation. 286 Technical Standard (2000) (Draft July 28, 2000) Headers 9366 AIO {_POSIX_AIO_LISTIO_MAX} 9367 The number of I/O operations that can be specified in a list I/O call. 9368 Value: 2 9369 AIO {_POSIX_AIO_MAX} 9370 The number of outstanding asynchronous I/O operations. 9371 Value: 1 9372 {_POSIX_ARG_MAX} 9373 Maximum length of argument to the exec functions including environment data. 9374 Value: 4 096 9375 {_POSIX_CHILD_MAX} 9376 Maximum number of simultaneous processes per real user ID. 9377 Value: 6 9378 TMR {_POSIX_DELAYTIMER_MAX} 9379 The number of timer expiration overruns. 9380 Value: 32 9381 {_POSIX_LINK_MAX} 9382 Maximum number of links to a single file. 9383 Value: 8 9384 {_POSIX_LOGIN_NAME_MAX} 9385 The size of the storage required for a login name, in bytes, including the terminating null. 9386 Value: 9 9387 {_POSIX_MAX_CANON} 9388 Maximum number of bytes in a terminal canonical input queue. 9389 Value: 255 9390 {_POSIX_MAX_INPUT} 9391 Maximum number of bytes allowed in a terminal input queue. 9392 Value: 255 9393 MSG {_POSIX_MQ_OPEN_MAX} 9394 The number of message queues that can be open for a single process. 9395 Value: 8 9396 MSG {_POSIX_MQ_PRIO_MAX} 9397 The maximum number of message priorities supported by the implementation. 9398 Value: 32 9399 Notes to Reviewers 9400 This section with side shading will not appear in the final copy. - Ed. 9401 D1, XSH, ERN 436 proposes increasing the value of {_POSIX_NAME_MAX} to 256. 9402 Similarly, it proposes {_POSIX_PATH_MAX} be 1 024. 9403 {_POSIX_NAME_MAX} 9404 Maximum number of bytes in a file name (not including terminating null). 9405 Value: 14 Base Definitions, Issue 6 287 Headers 9406 Notes to Reviewers 9407 This section with side shading will not appear in the final copy. - Ed. 9408 D1, XSH, ERN 19 proposes to increase {_POSIX_NGROUPS_MAX}, {_POSIX_OPEN_MAX}, 9409 and {_POSIX_CHILD_MAX} to their FIPS values (8, 20, 25) as with the limits equivalents 9410 without the leading _POSIX). 9411 {_POSIX_NGROUPS_MAX} 9412 Maximum number of simultaneous supplementary group IDs per process. 9413 Value: 0 9414 {_POSIX_OPEN_MAX} 9415 Maximum number of files that one process can have open at any one time. 9416 Value: 16 9417 {_POSIX_PATH_MAX} 9418 Maximum number of bytes in a path name. 9419 Value: 256 9420 {_POSIX_PIPE_BUF} 9421 Maximum number of bytes that is guaranteed to be atomic when writing to a pipe. 9422 Value: 512 9423 {_POSIX_RE_DUP_MAX} 9424 The number of repeated occurrences of a BRE permitted by the regexec( ) and regcomp( ) 9425 functions when using the interval notation {\(m,n\}; see Section 9.3.6 (on page 201). 9426 Value: 255 9427 RTS {_POSIX_RTSIG_MAX} 9428 The number of realtime signal numbers reserved for application use. 9429 Value: 8 9430 SEM {_POSIX_SEM_NSEMS_MAX} 9431 The number of semaphores that a process may have. 9432 Value: 256 9433 SEM {_POSIX_SEM_VALUE_MAX} 9434 The maximum value a semaphore may have. 9435 Value: 32 767 9436 RTS {_POSIX_SIGQUEUE_MAX} 9437 The number of queued signals that a process may send and have pending at the receiver(s) 9438 at any time. 9439 Value: 32 9440 {_POSIX_SSIZE_MAX} 9441 The value that can be stored in an object of type ssize_t. 9442 Value: 32 767 9443 {_POSIX_STREAM_MAX} 9444 The number of streams that one process can have open at one time. 9445 Value: 8 9446 SS|TSP {_POSIX_SS_REPL_MAX} 9447 The number of replenishment operations that may be simultaneously pending for a 9448 particular sporadic server scheduler. 9449 Value: 4 288 Technical Standard (2000) (Draft July 28, 2000) Headers 9450 {_POSIX_SYMLINK_MAX} 9451 The number of bytes in a symbolic link. 9452 Value: 255 9453 {_POSIX_SYMLOOP_MAX} 9454 The number of symbolic links that can be traversed in the resolution of a path name in the 9455 absence of a loop. 9456 Value: 8 | 9457 THR {_POSIX_THREAD_DESTRUCTOR_ITERATIONS} | 9458 The number of attempts made to destroy a thread's thread-specific data values on thread 9459 exit. 9460 Value: 4 | 9461 THR {_POSIX_THREAD_KEYS_MAX} | 9462 The number of data keys per process. 9463 Value: 128 | 9464 THR {_POSIX_THREAD_THREADS_MAX} | 9465 The number of threads per process. 9466 Value: 64 | 9467 TMR {_POSIX_TIMER_MAX} 9468 The per process number of timers. 9469 Value: 32 | 9470 TRC {_POSIX_TRACE_EVENT_NAME_MAX} | 9471 The length in bytes of a trace event name. | 9472 Value: 30 | 9473 TRC {_POSIX_TRACE_NAME_MAX} | 9474 The length in bytes of a trace generation version string or a trace stream name. | 9475 Value: 8 | 9476 TRC {_POSIX_TRACE_SYS_MAX} | 9477 The number of trace streams that may simultaneously exist in the system. | 9478 Value: 8 | 9479 TRC {_POSIX_TRACE_USER_EVENT_MAX} | 9480 The number of user trace event type identifiers that may simultaneously exist in a traced | 9481 process, including the predefined user trace event | 9482 POSIX_TRACE_UNNAMED_USER_EVENT. | 9483 Value: 32 | 9484 {_POSIX_TTY_NAME_MAX} 9485 The size of the storage required for a terminal device name, in bytes, including the 9486 terminating null. 9487 Value: 9 9488 {_POSIX_TZNAME_MAX} 9489 Maximum number of bytes supported for the name of a timezone (not of the TZ variable). 9490 Value: 6 9491 Note: The length given by {_POSIX_TZNAME_MAX} does not include the quoting 9492 characters mentioned in Section 8.3 (on page 192). 9493 {_POSIX2_BC_BASE_MAX} 9494 Maximum obase values allowed by the bc utility. 9495 Value: 99 Base Definitions, Issue 6 289 Headers 9496 {_POSIX2_BC_DIM_MAX} 9497 Maximum number of elements permitted in an array by the bc utility. 9498 Value: 2 048 9499 {_POSIX2_BC_SCALE_MAX} 9500 Maximum scale value allowed by the bc utility. 9501 Value: 99 9502 {_POSIX2_BC_STRING_MAX} 9503 Maximum length of a string constant accepted by the bc utility. 9504 Value: 1 000 9505 {_POSIX2_CHARCLASS_NAME_MAX} 9506 Maximum number of bytes in a character class name. 9507 Value: 14 9508 {_POSIX2_COLL_WEIGHTS_MAX} 9509 Maximum number of weights that can be assigned to an entry of the LC_COLLATE order 9510 keyword in the locale definition file; see Chapter 7 (on page 143). 9511 Value: 2 9512 {_POSIX2_EXPR_NEST_MAX} 9513 Maximum number of expressions that can be nested within parentheses by the expr utility. 9514 Value: 32 9515 {_POSIX2_LINE_MAX} 9516 Unless otherwise noted, the maximum length, in bytes, of a utility's input line (either 9517 standard input or another file), when the utility is described as processing text files. The 9518 length includes room for the trailing newline. 9519 Value: 2 048 9520 {_POSIX2_RE_DUP_MAX] 9521 Maximum number of repeated occurrences of a regular expression permitted when using 9522 the interval notation \{m,n\}; see Chapter 9 (on page 195). 9523 Value: 255 9524 XSI {_XOPEN_IOV_MAX} 9525 Maximum number of iovec structures that one process has available for use with readv( ) or 9526 writev( ). 9527 Value: 16 9528 9529 Numerical Limits 9530 The values in the following lists shall be defined in and are constant expressions 9531 XSI suitable for use in #if preprocessing directives. Moreover, except for {CHAR_BIT}, {DBL_DIG}, 9532 {DBL_MAX}, {FLT_DIG}, {FLT_MAX}, {LONG_BIT}, {WORD_BIT}, and {MB_LEN_MAX}, the 9533 symbolic names are defined as expressions of the correct type. 9534 If the value of an object of type char is treated as a signed integer when used in an expression, 9535 the value of {CHAR_MIN} is the same as that of {SCHAR_MIN} and the value of {CHAR_MAX} 9536 is the same as that of {SCHAR_MAX}. Otherwise, the value of {CHAR_MIN} is 0 and the value 9537 of {CHAR_MAX} is the same as that of {UCHAR_MAX}. 9538 {CHAR_BIT} 9539 Number of bits in a type char. 9540 Minimum Acceptable Value: 8 290 Technical Standard (2000) (Draft July 28, 2000) Headers 9541 {CHAR_MAX} 9542 Maximum value of type char. | 9543 Minimum Acceptable Value: {UCHAR_MAX} or {SCHAR_MAX} 9544 {INT_MAX} 9545 Maximum value of an int. 9546 Minimum Acceptable Value: 2 147 483 647 9547 XSI {LONG_BIT} 9548 Number of bits in a long. | 9549 Minimum Acceptable Value: 32 9550 {LONG_MAX} 9551 Maximum value of a long. | 9552 Minimum Acceptable Value: +2 147 483 647 9553 {MB_LEN_MAX} 9554 Maximum number of bytes in a character, for any supported locale. 9555 Minimum Acceptable Value: 1 9556 {SCHAR_MAX} 9557 Maximum value of type signed char. | 9558 Minimum Acceptable Value: +127 9559 {SHRT_MAX} 9560 Maximum value of type short. | 9561 Minimum Acceptable Value: +32 767 9562 {SSIZE_MAX} 9563 Maximum value of an object of type ssize_t. 9564 Minimum Acceptable Value: {_POSIX_SSIZE_MAX} 9565 {UCHAR_MAX} 9566 Maximum value of type unsigned char. | 9567 Minimum Acceptable Value: 255 9568 {UINT_MAX} 9569 Maximum value of type unsigned. | 9570 Minimum Acceptable Value: 4 294 967 295 9571 {ULONG_MAX} 9572 Maximum value of type unsigned long. | 9573 Minimum Acceptable Value: 4 294 967 295 9574 {USHRT_MAX} 9575 Maximum value for a type unsigned short. | 9576 Minimum Acceptable Value: 65 535 9577 XSI {WORD_BIT} 9578 Number of bits in a word or type int. 9579 Minimum Acceptable Value: 16 9580 {CHAR_MIN} 9581 Minimum value of type char. | 9582 Maximum Acceptable Value: {SCHAR_MIN} or 0 9583 {INT_MIN} 9584 Minimum value of type int. | 9585 Maximum Acceptable Value: -2 147 483 647 Base Definitions, Issue 6 291 Headers 9586 {LONG_MIN} 9587 Minimum value of type long. | 9588 Maximum Acceptable Value: -2 147 483 647 9589 {SCHAR_MIN} 9590 Minimum value of type signed char. | 9591 Maximum Acceptable Value: -127 9592 {SHRT_MIN} 9593 Minimum value of type short. | 9594 Maximum Acceptable Value: -32 767 | 9595 {LLONG_MIN} | 9596 Minimum value of type long long. | 9597 Maximum Acceptable Value: -9223372036854775807 | 9598 {LLONG_MAX} | 9599 Maximum value of type long long. | 9600 Minimum Acceptable Value: +9223372036854775807 | 9601 {ULLONG_MAX} | 9602 Maximum value of type unsigned long long. | 9603 Minimum Acceptable Value: 18446744073709551615 | 9604 Other Invariant Values 9605 XSI The following constants shall be defined on all implementations in : | 9606 XSI {CHARCLASS_NAME_MAX} 9607 Maximum number of bytes in a character class name. 9608 Minimum Acceptable Value: 14 9609 XSI {NL_ARGMAX} 9610 Maximum value of digit in calls to the printf( ) and scanf( ) functions. 9611 Minimum Acceptable Value: 9 9612 XSI {NL_LANGMAX} 9613 Maximum number of bytes in a LANG name. 9614 Minimum Acceptable Value: 14 9615 XSI {NL_MSGMAX} 9616 Maximum message number. 9617 Minimum Acceptable Value: 32 767 9618 XSI {NL_NMAX} 9619 Maximum number of bytes in an N-to-1 collation mapping. 9620 Minimum Acceptable Value: '*' 9621 XSI {NL_SETMAX} 9622 Maximum set number. 9623 Minimum Acceptable Value: 255 9624 XSI {NL_TEXTMAX} 9625 Maximum number of bytes in a message string. 9626 Minimum Acceptable Value: {_POSIX2_LINE_MAX} 9627 XSI {NZERO} 9628 Default process priority. 9629 Minimum Acceptable Value: 20 292 Technical Standard (2000) (Draft July 28, 2000) Headers 9630 XSI {TMP_MAX} 9631 Minimum number of unique path names generated by tmpnam( ). Maximum number of 9632 times an application can call tmpnam( ) reliably. (LEGACY) 9633 Minimum Acceptable Value: 10 000 9634 APPLICATION USAGE 9635 None. 9636 RATIONALE 9637 A request was made to reduce the value of {_POSIX_LINK_MAX} from the value of 8 specified 9638 for it in the POSIX.1-1990 standard to 2. The standard developers decided to deny this request 9639 for several reasons. 9640 * They wanted to avoid making any changes to the standard that could break conforming 9641 applications, and the requested change could have that effect. 9642 * The use of multiple hard links to a file cannot always be replaced with use of symbolic links. 9643 Symbolic links are semantically different from hard links in that they associate a path name 9644 with another path name rather than a path name with a file. This has implications for access 9645 control, file permanence, and transparency. 9646 * The original standard developers had considered the issue of allowing for implementations | 9647 that did not in general support hard links, and decided that this would reduce consensus on | 9648 the standard. | 9649 Systems that support historical versions of the development option of the ISO POSIX-2 standard 9650 retain the name {_POSIX2_RE_DUP_MAX} as an alias for {_POSIX_RE_DUP_MAX}. 9651 {PATH_MAX} 9652 IEEE PASC Interpretation 1003.1 #15 addressed the inconsistency in the standard with the | 9653 definition of path name and the description of {PATH_MAX}, allowing application writers | 9654 to allocate either {PATH_MAX} or {PATH_MAX}+1 bytes. The inconsistency has been 9655 removed by correction to the {PATH_MAX} definition to include the null character. With 9656 this change, applications that previously allocated {PATH_MAX} bytes will continue to 9657 succeed. 9658 {SYMLINK_MAX} 9659 This symbol refers to space for data that is stored in the file system, as opposed to 9660 {PATH_MAX} which is the length of a name that can be passed to a function. In some 9661 existing implementations, the file names pointed to by symbolic links are stored in the 9662 inodes of the links, so it is important that {SYMLINK_MAX} not be constrained to be as 9663 large as {PATH_MAX}. 9664 FUTURE DIRECTIONS 9665 None. 9666 SEE ALSO 9667 The System Interfaces volume of IEEE Std. 1003.1-200x, fpathconf( ), pathconf( ), sysconf( ) 9668 CHANGE HISTORY 9669 First released in Issue 1. 9670 Issue 4 9671 A sentence is added to the DESCRIPTION indicating that names beginning with _POSIX can be 9672 found in . 9673 The {PASS_MAX} and {TMP_MAX} symbols are marked LEGACY. | Base Definitions, Issue 6 293 Headers 9674 Use of the terms ``bytes'' and ``characters'' is rationalized to make it clear when the description is 9675 referring to either single-byte values or possibly multi-byte characters. 9676 {CHARCLASS_NAME_MAX} is added to the list of Other Invariant Values and marked as an 9677 extension. 9678 This entry is largely restructured to improve symbol grouping. A great many symbols, too 9679 numerous to mention, have also been added for alignment with the ISO POSIX-2 standard. 9680 The following changes are incorporated for alignment with the ISO C standard: 9681 * The constants {INT_MIN}, {LONG_MIN}, and {SHRT_MIN} are changed from values ending 9682 in 8 to ones ending in 7. 9683 * The {DBL_DIG}, {DBL_MAX}, {FLT_DIG}, and {FLT_MAX} symbols are marked both as | 9684 extensions and LEGACY. | 9685 * The {LONG_BIT} and {WORD_BIT} symbols are marked as extensions. 9686 * The {DBL_MIN} and {FLT_MIN} symbols are withdrawn. 9687 * Text introducing numerical limits now indicates that they are constant expressions suitable 9688 for use in #if preprocessing directives. 9689 The following change is incorporated for alignment with the FIPS requirements: 9690 * The minimum acceptable value for {NGROUPS_MAX} is changed from 9691 {_POSIX_NGROUPS_MAX} to 8. This is marked as as extension. 9692 Issue 4, Version 2 9693 The DESCRIPTION is revised for X/OPEN UNIX conformance as follows: 9694 * Under Runtime Invariant Values, {ATEXIT_MAX}, {IOV_MAX}, {PAGESIZE}, and 9695 {PAGE_SIZE} are added. 9696 * Under Minimum Values, {_XOPEN_IOV_MAX} is added. 9697 Issue 5 9698 The DESCRIPTION is updated for alignment with the POSIX Realtime Extension and the POSIX 9699 Threads Extension. 9700 {FILESIZEBITS} added for the Large File Summit extensions. 9701 The minimum acceptable values for {INT_MAX}, {INT_MIN}, and {UINT_MAX} are changed to 9702 make 32-bit values the minimum requirement. 9703 The entry is restructured to improve readability. 9704 Issue 6 9705 The Open Group corrigenda item U033/4 has been applied. The wording is made clear for 9706 {CHAR_MIN}, {INT_MIN}, {LONG_MIN}, {SCHAR_MIN}, and {SHRT_MIN} that these are 9707 maximum acceptable values. 9708 The following new requirements on POSIX implementations derive from alignment with the 9709 Single UNIX Specification: 9710 * The minimum value for {CHILD_MAX} is 25. This is a FIPS requirement. 9711 * The minimum value for {OPEN_MAX} is 20. This is a FIPS requirement. 9712 * The minimum value for {NGROUPS_MAX} is 8. This is also a FIPS requirement. 9713 Symbolic constants are added for {_POSIX_SYMLINK_MAX}, {_POSIX_SYMLOOP_MAX}, 9714 {_POSIX_RE_DUP_MAX}, {RE_DUP_MAX}, {SYMLOOP_MAX}, and {SYMLINK_MAX}. 294 Technical Standard (2000) (Draft July 28, 2000) Headers 9715 The following values are added for alignment with IEEE Std. 1003.1d-1999: 9716 {_POSIX_SS_REPL_MAX} 9717 {SS_REPL_MAX} 9718 {POSIX_ALLOC_SIZE_MIN} 9719 {POSIX_REC_INCR_XFER_SIZE} 9720 {POSIX_REC_MAX_XFER_SIZE} 9721 {POSIX_REC_MIN_XFER_SIZE} 9722 {POSIX_REC_XFER_ALIGN} 9723 Reference to CLOCK_MONOTONIC is added in the description of {_POSIX_CLOCKRES_MIN} 9724 for alignment with IEEE Std. 1003.1j-2000. | 9725 The constants {LLONG_MIN}, {LLONG_MAX}, and {ULLONG_MAX} are added for alignment | 9726 with the ISO/IEC 9899: 1999 standard. | 9727 The following values are added for alignment with IEEE Std. 1003.1q-2000: | 9728 {_POSIX_TRACE_EVENT_NAME_MAX}, {_POSIX_TRACE_NAME_MAX}, | 9729 {_POSIX_TRACE_SYS_MAX}, {_POSIX_TRACE_USER_EVENT_MAX}, | 9730 {TRACE_EVENT_NAME_MAX}, {TRACE_NAME_MAX}, {TRACE_SYS_MAX}, | 9731 {TRACE_USER_EVENT_MAX} | Base Definitions, Issue 6 295 Headers 9732 NAME 9733 locale.h - category macros 9734 SYNOPSIS 9735 #include 9736 DESCRIPTION 9737 CX The functionality described on this reference page extends the ISO C standard. Applications 9738 shall define the appropriate feature test macro (see the System Interfaces volume of 9739 IEEE Std. 1003.1-200x, Section 2.2, The Compilation Environment) to enable the visibility of 9740 symbols in this header. 9741 The header shall provide a definition for structure lconv, which shall include at least 9742 the following members. (See the definitions of LC_MONETARY in the Section 7.3.3 (on page 9743 163), and Section 7.3.4 (on page 166).) 9744 char *currency_symbol 9745 char *decimal_point 9746 char frac_digits 9747 char *grouping 9748 char *int_curr_symbol 9749 char int_frac_digits 9750 char int_n_cs_precedes 9751 char int_n_sep_by_space 9752 char int_n_sign_posn 9753 char int_p_cs_precedes 9754 char int_p_sep_by_space 9755 char int_p_sign_posn 9756 char *mon_decimal_point 9757 char *mon_grouping 9758 char *mon_thousands_sep 9759 char *negative_sign 9760 char n_cs_precedes 9761 char n_sep_by_space 9762 char n_sign_posn 9763 char *positive_sign 9764 char p_cs_precedes 9765 char p_sep_by_space 9766 char p_sign_posn 9767 char *thousands_sep 9768 The header shall define NULL (as defined in ) and at least the following as 9769 macros: 9770 LC_ALL 9771 LC_COLLATE 9772 LC_CTYPE 9773 LC_MESSAGES 9774 LC_MONETARY 9775 LC_NUMERIC 9776 LC_TIME 9777 which shall expand to distinct integral constant expressions, for use as the first argument to the | 9778 setlocale( ) function. 296 Technical Standard (2000) (Draft July 28, 2000) Headers 9779 Additional macro definitions, beginning with the characters LC_ and an uppercase letter, may 9780 also be given here. 9781 The following shall be declared as functions and may also be defined as macros. Function 9782 prototypes shall be provided for use with an ISO C standard compiler. 9783 struct lconv *localeconv (void); 9784 char setlocale(int, const char *); 9785 APPLICATION USAGE 9786 None. 9787 RATIONALE 9788 None. 9789 FUTURE DIRECTIONS 9790 None. 9791 SEE ALSO 9792 The System Interfaces volume of IEEE Std. 1003.1-200x, localeconv( ), setlocale( ), Chapter 8 (on 9793 page 187) 9794 CHANGE HISTORY 9795 First released in Issue 3. 9796 Entry included for alignment with the ISO C standard. 9797 Issue 4 9798 The following changes are incorporated for alignment with the ISO C standard: 9799 * The function declarations in this header are expanded to full ISO C standard prototypes. 9800 * The definition of struct lconvisadded. 9801 * A reference to is added for the definition of NULL. 9802 Issue 6 | 9803 The lconv structure is expanded with new members (int_n_cs_precedes, int_n_sep_by_space, | 9804 int_n_sign_posn, int_p_cs_precedes, int_p_sep_by_space, and int_p_sign_posn) for alignment | 9805 with the ISO/IEC 9899: 1999 standard. | Base Definitions, Issue 6 297 Headers 9806 NAME 9807 math.h - mathematical declarations 9808 SYNOPSIS 9809 #include 9810 DESCRIPTION 9811 CX The functionality described on this reference page extends the ISO C standard. Applications 9812 shall define the appropriate feature test macro (see the System Interfaces volume of 9813 IEEE Std. 1003.1-200x, Section 2.2, The Compilation Environment) to enable the visibility of 9814 symbols in this header. 9815 The header shall include definitions for at least the following types: | 9816 float_t A floating type at least as wide as float. | 9817 double_t A floating type at least as wide as double, and at least as wide as float_t. | 9818 If FLT_EVAL_METHOD equals 0, float_t and double_t shall be float and double, respectively; if | 9819 FLT_EVAL_METHOD equals 1, they shall both be double; if FLT_EVAL_METHOD equals 2, | 9820 they shall both be long double; for other values of FLT_EVAL_METHOD, they are otherwise | 9821 implementation-defined. | 9822 The header shall define the following macros, where real-floating indicates that the | 9823 argument shall be an expression of real-floating type: | 9824 int fpclassify(real-floating x); | 9825 int isfinite(real-floating x); | 9826 int isinf(real-floating x); | 9827 int isnan(real-floating x); | 9828 int isnormal(real-floating x); | 9829 int signbit(real-floating x); | 9830 int isgreater(real-floating x, real-floating y); | 9831 int isgreaterequal(real-floating x, real-floating y); | 9832 int isless(real-floating x, real-floating y); | 9833 int islessequal(real-floating x, real-floating y); | 9834 int islessgreater(real-floating x, real-floating y); | 9835 int isunordered(real-floating x, real-floating y); | 9836 The header shall provide for the following constants. The values are of type double | 9837 and are accurate within the precision of the double type. 9838 XSI M_E Value of e 9839 M_LOG2E Value of log2e 9840 M_LOG10E Value of log10e 9841 M_LN2 Value of loge2 9842 M_LN10 Value of loge10 9843 M_PI Value of 9844 M_PI_2 Value of /2 9845 M_PI_4 Value of /4 9846 M_1_PI Value of 1/ 9847 M_2_PI Value of 2/ 298 Technical Standard (2000) (Draft July 28, 2000) Headers 9848 M_2_SQRTPI Value of 2/ 9849 M_SQRT2 Value of 2 9850 M_SQRT1_2 Value of 1/ 2 9851 The header shall define the following symbolic constants: 9852 XSI MAXFLOAT Value of maximum non-infinite single-precision floating-point number. 9853 HUGE_VAL A positive double expression, not necessarily representable as a float. Used 9854 as an error value returned by the mathematics library. HUGE_VAL evaluates | 9855 to + on systems supporting IEEE Std. 754-1985. | 9856 HUGE_VALF A positive float constant expression. Used as an error value returned by the | 9857 mathematics library. HUGE_VALF evaluates to +infinity on systems | 9858 supporting IEEE Std. 754-1985. | 9859 HUGE_VALD A positive long double constant expression. Used as an error value returned | 9860 by the mathematics library. HUGE_VALD evaluates to +infinity on systems | 9861 supporting IEEE Std. 754-1985. | 9862 INFINITY A constant expression of type float representing positive or unsigned infinity, | 9863 if available; else a positive constant of type float that overflows at translation | 9864 time. | 9865 NAN A constant expression of type float representing a quiet NaN. This symbolic | 9866 constant is only defined if the implementation supports quiet NaNs for the | 9867 float type. | 9868 The following macros shall be defined for number classification. They represent the mutually- | 9869 exclusive kinds of floating-point values. They expand to integer constant expressions with | 9870 distinct values. Additional implementation-defined floating-point classifications, with macro | 9871 definitions beginning with FP_ and an uppercase letter, may also be specified by the | 9872 implementation. | 9873 FP_INFINITE | 9874 FP_NAN | 9875 FP_NORMAL | 9876 FP_SUBNORMAL | 9877 FP_ZERO | 9878 The following macros are optional. If FP_FATS_FMA is defined, it shall indicate that the fma( ) | 9879 function generally executes about as fast as, or faster than, a multiply and an add of double | 9880 operands. | 9881 FP_FAST_FMA | 9882 FP_FAST_FMAF | 9883 FP_FAST_FMAL | 9884 FP_FAST_FMAF and FP_FAST_FMAL are, respectively, float and long double analogs of | 9885 FP_FAST_FMA. | 9886 The following macros shall expand to integer constant expressions whose values are returned by | 9887 ilogb(x) if x is zero or NaN, respectively. The value of FP_ILOGB0 shall be either {INT_MIN} or | 9888 -{INT_MAX}. The value of FP_ILOGBNAN shall be either {INT_MAX} or {INT_MIN}. | 9889 FP_ILOGB0 | 9890 FP_ILOGBNAN | Base Definitions, Issue 6 299 Headers 9891 The following macros shall expand to the integer constants 1 and 2, respectively; | 9892 MATH_ERRNO | 9893 MATH_ERREXCEPT | 9894 The following macro shall expand to an expression that has type int and the value | 9895 MATH_ERRNO, MATH_ERREXCEPT, or the bitwise-inclusive OR of both. The value of | 9896 math_errhandling is constant for the duration of the program. It is unspecified whether | 9897 math_errhandling is a macro or an identifier with external linkage. If a macro definition is | 9898 suppressed or a program defines an identifier with the name math_errhandling, the behavior is | 9899 undefined. If the expression math_errhandling & MATH_ERREXCEPT can be non-zero, the | 9900 implementation shall define the macros FE_DIVBYZERO, FE_INVALID, and FE_OVERFLOW in | 9901 . | 9902 math_errhandling | 9903 The following shall be declared as functions and may also be defined as macros. Function | 9904 prototypes shall be provided for use with an ISO C standard compiler. 9905 double acos(double); 9906 float acosf(float); 9907 XSI double acosh(double); 9908 float acoshf(float); 9909 long double acoshl(long double); 9910 long double acosl(long double); 9911 double asin(double); 9912 float asinf(float); 9913 XSI double asinh(double); 9914 float asinhf(float); 9915 long double asinhl(long double); 9916 long double asinl(long double); 9917 double atan(double); 9918 double atan2(double, double); 9919 float atan2f(float, float); 9920 long double atan2l(long double, long double); 9921 float atanf(float); 9922 XSI double atanh(double); 9923 float atanhf(float); 9924 long double atanhl(long double); 9925 long double atanl(long double); 9926 XSI double cbrt(double); 9927 float cbrtf(float); 9928 long double cbrtl(long double); 9929 double ceil(double); 9930 float ceilf(float); 9931 long double ceill(long double); 9932 double copysign(double, double); 9933 float copysignf(float, float); 9934 long double copysignl(long double, long double); 9935 double cos(double); 9936 float cosf(float); 9937 double cosh(double); 9938 float coshf(float); 9939 long double coshl(long double); 9940 long double cosl(long double); 300 Technical Standard (2000) (Draft July 28, 2000) Headers 9941 XSI double erf(double); 9942 double erfc(double); 9943 float erfcf(float); 9944 long double erfcl(long double); 9945 float erff(float); 9946 long double erfl(long double); 9947 double exp(double); 9948 double exp2(double); 9949 float exp2f(float); 9950 long double exp2l(long double); 9951 float expf(float); 9952 long double expl(long double); 9953 XSI double expm1(double); 9954 float expm1f(float); 9955 long double expm1l(long double); 9956 double fabs(double); 9957 float fabsf(float); 9958 long double fabsl(long double); 9959 double fdim(double, double); 9960 float fdimf(float, float); 9961 long double fdiml(long double, long double); 9962 double floor(double); 9963 float floorf(float); 9964 long double floorl(long double); 9965 double fma(double, double, double); 9966 float fmaf(float, float, float); 9967 long double fmal(long double, long double, long double); 9968 double fmax(double, double); 9969 float fmaxf(float, float); 9970 long double fmaxl(long double, long double); 9971 double fmin(double, double); 9972 float fminf(float, float); 9973 long double fminl(long double, long double); 9974 double fmod(double, double); 9975 float fmodf(float, float); 9976 long double fmodl(long double, long double); 9977 double frexp(double, int *); 9978 float frexpf(float value, int *); 9979 long double frexpl(long double value, int *); 9980 XSI double hypot(double, double); 9981 float hypotf(float, float); 9982 long double hypotl(long double, long double); 9983 XSI int ilogb(double); 9984 int ilogbf(float); 9985 int ilogbl(long double); 9986 XSI int isnan(double); 9987 double j0(double); 9988 double j1(double); 9989 double jn(int, double); 9990 double ldexp(double, int); 9991 float ldexpf(float, int); 9992 long double ldexpl(long double, int); Base Definitions, Issue 6 301 Headers 9993 XSI double lgamma(double); 9994 float lgammaf(float); 9995 long double lgammal(long double); 9996 double log(double); 9997 double log10(double); 9998 float log10f(float); 9999 long double log10l(long double); 10000 XSI double log1p(double); 10001 float log1pf(float); 10002 long double log1pl(long double); 10003 double log2(double); 10004 float log2f(float); 10005 long double log2l(long double); 10006 XSI double logb(double); 10007 float logbf(float); 10008 long double logbl(long double); 10009 float logf(float); 10010 long double logl(long double); 10011 long long llrint(double); 10012 long long llrintf(float); 10013 long long llrintl(long double); 10014 long long llround(double); 10015 long long llroundf(float); 10016 long long llroundl(long double); 10017 long lrint(double); 10018 long lrintf(float); 10019 long lrintl(long double); 10020 long lround(double); 10021 long lroundf(float); 10022 long lroundl(long double); 10023 double modf(double, double *); 10024 float modff(float, float *); 10025 long double modfl(long double, long double *); 10026 double nan(const char *); 10027 float nanf(const char *); 10028 long double nanl(const char *); 10029 double nearbyint(double); 10030 float nearbyintf(float); 10031 long double nearbyintl(long double); 10032 XSI double nextafter(double, double); 10033 float nextafterf(float, float); 10034 long double nextafterl(long double, long double); 10035 double nexttoward(double, long double); 10036 float nexttowardf(float, long double); 10037 long double nexttowardl(long double, long double); 10038 double pow(double, double); 10039 float powf(float, float); 10040 long double powl(long double, long double); 10041 XSI double remainder(double, double); 10042 float remainderf(float, float); 10043 long double remainderl(long double, long double); 10044 double remquo(double, double, int *); 302 Technical Standard (2000) (Draft July 28, 2000) Headers 10045 float remquof(float, float, int *); 10046 long double remquol(long double, long double, int *); 10047 XSI double rint(double); 10048 float rintf(float); 10049 long double rintl(long double); 10050 double round(double); 10051 float roundf(float); 10052 long double roundl(long double); 10053 XSI double scalb(double, double); 10054 double scalbln(double, long); 10055 float scalblnf(float, long); 10056 long double scalblnl(long double, long); 10057 double scalbn(double, int); 10058 float scalbnf(float, int); 10059 long double scalbnl(long double, int); 10060 double sin(double); 10061 float sinf(float); 10062 double sinh(double); 10063 float sinhf(float); 10064 long double sinhl(long double); 10065 long double sinl(long double); 10066 double sqrt(double); 10067 float sqrtf(float); 10068 long double sqrtl(long double); 10069 double tan(double); 10070 float tanf(float); 10071 double tanh(double); 10072 float tanhf(float); 10073 long double tanhl(long double); 10074 long double tanl(long double); 10075 double tgamma(double); 10076 float tgammaf(float); 10077 long double tgammal(long double); 10078 double trunc(double); 10079 float truncf(float); 10080 long double truncl(long double); 10081 XSI double y0(double); 10082 double y1(double); 10083 double yn(int, double); 10084 10085 The following external variable shall be defined: 10086 XSI extern int signgam; 10087 Base Definitions, Issue 6 303 Headers 10088 APPLICATION USAGE 10089 The FP_CONTRACT pragma can be used to allow (if the state is on) or disallow (if the state is | 10090 off) the implementation to contract expressions. Each pragma can occur either outside external | 10091 declarations or preceding all explicit declarations and statements inside a compound statement. | 10092 When outside external declarations, the pragma takes effect from its occurrence until another | 10093 FP_CONTRACT pragma is encountered, or until the end of the translation unit. When inside a | 10094 compound statement, the pragma takes effect from its occurrence until another FP_CONTRACT | 10095 pragma is encountered (including within a nested compound statement), or until the end of the | 10096 compound statement; at the end of a compound statement the state for the pragma is restored to | 10097 its condition just before the compound statement. If this pragma is used in any other context, the | 10098 behavior is undefined. The default state (on or off) for the pragma is implementation-defined. | 10099 RATIONALE 10100 Before the ISO/IEC 9899: 1999 standard, the math library was defined only for the floating type | 10101 double. All the names formed by appending 'f' or 'l' to a name in were reserved | 10102 to allow for the definition of float and long double libraries; and the ISO/IEC 9899: 1999 | 10103 standard provides for all three versions of math functions. | 10104 The functions ecvt( ), fcvt( ), and gcvt( ) have been dropped from the ISO C standard since their | 10105 capability is available through sprintf( ). These are provided on XSI-conformant systems | 10106 supporting the Legacy Option Group. | 10107 FUTURE DIRECTIONS 10108 None. 10109 SEE ALSO 10110 The System Interfaces volume of IEEE Std. 1003.1-200x, acos( ), acosh( ), asin( ), atan( ), atan2( ), 10111 cbrt( ), ceil( ), cos( ), cosh( ), erf( ), exp( ), expm1( ), fabs( ), floor( ), fmod( ), frexp( ), hypot( ), ilogb( ), 10112 isnan( ), j0( ), ldexp( ), lgamma( ), log( ), log10( ), log1p( ), logb( ), modf( ), nextafter( ), pow( ), 10113 remainder( ), rint( ), scalb( ), sin( ), sinh( ), sqrt( ), tan( ), tanh( ), y0( ) 10114 CHANGE HISTORY 10115 First released in Issue 1. 10116 Issue 4 10117 The constants M_E and MAXFLOAT are marked as extensions. 10118 The functions declared in this header are subdivided into those defined in the ISO C standard, 10119 and those defined only by The Open Group. Functions in the latter group are marked as 10120 extensions, as is the external variable signgam. 10121 The following changes are incorporated for alignment with the ISO C standard: 10122 * The description of HUGE_VAL is changed to indicate that this value is not necessarily 10123 representable as a float. 10124 * The function declarations in this header are expanded to full ISO C standard prototypes. 10125 Issue 4, Version 2 10126 The following change is incorporated for X/OPEN UNIX conformance: 10127 * The acosh( ), asinh( ), atanh( ), cbrt( ), expm1( ), ilogb( ), log1p( ), logb( ), nextafter( ), remainder( ), 10128 rint( ), and scalb( ) functions are added to the list of functions declared in this header. 10129 Issue 6 | 10130 This reference page is updated to align with the ISO/IEC 9899: 1999 standard. | 304 Technical Standard (2000) (Draft July 28, 2000) Headers 10131 NAME 10132 monetary.h - monetary types 10133 SYNOPSIS 10134 XSI #include 10135 10136 DESCRIPTION 10137 The header shall define the following data types through typedef: 10138 size_t As described in . 10139 ssize_t As described in . 10140 The following shall be declared as a function and may also be defined as a macro. Function 10141 prototypes shall be provided for use with an ISO C standard compiler. 10142 ssize_t strfmon(char *restrict, size_t, const char *restrict, ...); 10143 APPLICATION USAGE 10144 None. 10145 RATIONALE 10146 None. 10147 FUTURE DIRECTIONS 10148 None. 10149 SEE ALSO 10150 The System Interfaces volume of IEEE Std. 1003.1-200x, strfmon( ) 10151 CHANGE HISTORY 10152 First released in Issue 4. | 10153 Issue 6 | 10154 The restrict keyword is added to the prototype for strfmon( ). | Base Definitions, Issue 6 305 Headers 10155 NAME 10156 mqueue.h - message queues (REALTIME) 10157 SYNOPSIS 10158 MSG #include 10159 10160 DESCRIPTION 10161 The header shall define the mqd_t type, which is used for message queue 10162 descriptors. This is not an array type. | 10163 The header shall define the sigevent structure (as described in ) and the 10164 mq_attr structure, which is used in getting and setting the attributes of a message queue. 10165 Attributes are initially set when the message queue is created. An mq_attr structure shall have at 10166 least the following fields: 10167 long mq_flags Message queue flags. 10168 long mq_maxmsg Maximum number of messages. 10169 long mq_msgsize Maximum message size. 10170 long mq_curmsgs Number of messages currently queued. 10171 The following shall be declared as functions and may also be declared as macros. Function 10172 prototypes shall be provided for use with an ISO C standard compiler. 10173 int mq_close(mqd_t); 10174 int mq_getattr(mqd_t, struct mq_attr *); 10175 int mq_notify(mqd_t, const struct sigevent *); 10176 mqd_t mq_open(const char *, int, ...); 10177 ssize_t mq_receive(mqd_t, char *, size_t, unsigned *); 10178 int mq_send(mqd_t, const char *, size_t, unsigned ); 10179 int mq_setattr(mqd_t, const struct mq_attr *restrict, 10180 struct mq_attr *restrict); 10181 TMO int mq_timedreceive(mqd_t, char *restrict, size_t, 10182 unsigned *restrict, const struct timespec *restrict); 10183 int mq_timedsend(mqd_t, const char *, size_t, unsigned , 10184 const struct timespec *); 10185 int mq_unlink(const char *); 10186 Notes to Reviewers | 10187 This section with side shading will not appear in the final copy. - Ed. | 10188 D3, XBD, ERN 163: The return type from mq_timedreceive() should be ssize_t and not int. An | 10189 interpretation should be filed against .1d to bring this change into scope. | 10190 Inclusion of the header may make visible symbols defined in the headers , | 10191 , , and . 306 Technical Standard (2000) (Draft July 28, 2000) Headers 10192 APPLICATION USAGE 10193 None. 10194 RATIONALE 10195 None. 10196 FUTURE DIRECTIONS 10197 None. 10198 SEE ALSO 10199 , , , , the System Interfaces volume of 10200 IEEE Std. 1003.1-200x, mq_close( ), mq_getattr( ), mq_notify( ), mq_open( ), mq_receive( ), mq_send( ), 10201 mq_setattr( ), mq_timedreceive( ), mq_timedsend( ), mq_unlink( ) 10202 CHANGE HISTORY 10203 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 10204 Issue 6 10205 The header is marked as part of the Message Passing option. | 10206 The mq_timedreceive( ) and mq_timedsend( ) functions are added for alignment with 10207 IEEE Std. 1003.1d-1999. | 10208 The restrict keyword is added to the prototypes for mq_setattr( ) and mq_timedreceive( ). | Base Definitions, Issue 6 307 Headers 10209 NAME 10210 ndbm.h - definitions for ndbm database operations 10211 SYNOPSIS 10212 XSI #include 10213 10214 DESCRIPTION 10215 The header shall define the datum type as a structure that includes at least the 10216 following members: | 10217 void *dptr A pointer to the application's data. | 10218 size_t dsize The size of the object pointed to by dptr. | 10219 The size_t type shall be defined through typedef as described in . | 10220 The header shall define the DBM type through typedef. 10221 The following constants shall be defined as possible values for the store_mode argument to 10222 dbm_store( ): 10223 DBM_INSERT Insertion of new entries only. 10224 DBM_REPLACE Allow replacing existing entries. 10225 The following shall be declared as functions and may also be defined as macros. Function 10226 prototypes shall be provided for use with an ISO C standard compiler. 10227 int dbm_clearerr(DBM *); 10228 void dbm_close(DBM *); 10229 int dbm_delete(DBM *, datum); 10230 int dbm_error(DBM *); 10231 datum dbm_fetch(DBM *, datum); 10232 datum dbm_firstkey(DBM *); 10233 datum dbm_nextkey(DBM *); 10234 DBM *dbm_open(const char *, int, mode_t); 10235 int dbm_store(DBM *, datum, datum, int); 10236 The mode_t type shall be defined through typedef as described in . 10237 APPLICATION USAGE 10238 None. 10239 RATIONALE 10240 None. 10241 FUTURE DIRECTIONS 10242 None. 10243 SEE ALSO 10244 The System Interfaces volume of IEEE Std. 1003.1-200x, dbm_clearerr( ) 10245 CHANGE HISTORY 10246 First released in Issue 4, Version 2. 10247 Issue 5 10248 References to the definitions of size_t and mode_t are added to the DESCRIPTION. 308 Technical Standard (2000) (Draft July 28, 2000) Headers 10249 NAME 10250 net/if.h - sockets local interfaces 10251 SYNOPSIS 10252 #include 10253 DESCRIPTION 10254 The header shall define the if_nameindex structure that includes at least the 10255 following members: 10256 unsigned if_index Numeric index of the interface. 10257 char *if_name Null-terminated name of the interface. 10258 The header shall define the following macro for the length of a buffer containing an 10259 interface name (including the terminating NULL character): 10260 IF_NAMESIZE Interface name length. 10261 The following shall be declared as functions, and may also be defined as macros. Function 10262 prototypes shall be provided for use with an ISO C standard compiler. 10263 unsigned if_nametoindex(const char*); 10264 char *if_indextoname(unsigned, char*); 10265 struct if_nameindex *if_nameindex(void); 10266 void if_freenameindex(struct if_nameindex*); 10267 APPLICATION USAGE 10268 None. 10269 RATIONALE 10270 None. 10271 FUTURE DIRECTIONS 10272 None. 10273 SEE ALSO 10274 The System Interfaces volume of IEEE Std. 1003.1-200x, if_freenameindex( ), if_indextoname( ), 10275 if_nameindex( ), if_nametoindex( ) 10276 CHANGE HISTORY 10277 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. | Base Definitions, Issue 6 309 Headers 10278 NAME 10279 netdb.h - definitions for network database operations 10280 SYNOPSIS 10281 #include 10282 DESCRIPTION 10283 The header may make available the in_port_t type and the in_addr_t type as defined 10284 in . 10285 The header shall define the hostent structure that includes at least the following 10286 members: 10287 char *h_name Official name of the host. 10288 char **h_aliases A pointer to an array of pointers to 10289 alternative host names, terminated by a 10290 null pointer. 10291 int h_addrtype Address type. 10292 int h_length The length, in bytes, of the address. 10293 char **h_addr_list A pointer to an array of pointers to network 10294 addresses (in network byte order) for the host, 10295 terminated by a null pointer. 10296 The header shall define the netent structure that includes at least the following 10297 members: 10298 char *n_name Official, fully-qualified (including the 10299 domain) name of the host. 10300 char **n_aliases A pointer to an array of pointers to 10301 alternative network names, terminated by a 10302 null pointer. 10303 int n_addrtype The address type of the network. 10304 uint32_t n_net The network number, in host byte order. 10305 The uint32_t type shall be defined as described in . 10306 The header shall define the protoent structure that includes at least the following 10307 members: 10308 char *p_name Official name of the protocol. 10309 char **p_aliases A pointer to an array of pointers to 10310 alternative protocol names, terminated by 10311 a null pointer. 10312 int p_proto The protocol number. 10313 The header shall define the servent structure that includes at least the following 10314 members: 10315 char *s_name Official name of the service. 10316 char **s_aliases A pointer to an array of pointers to 10317 alternative service names, terminated by 10318 a null pointer. 10319 int s_port The port number at which the service 10320 resides, in network byte order. 10321 char *s_proto The name of the protocol to use when 10322 contacting the service. 310 Technical Standard (2000) (Draft July 28, 2000) Headers 10323 The header shall define the IPPORT_RESERVED macro with the value of the highest 10324 reserved Internet port number. 10325 When the header is included, h_errno shall be available as a modifiable l-value of type 10326 int. It is unspecified whether h_errno is a macro or an identifier declared with external linkage. 10327 The header shall define the following macros for use as error values for 10328 gethostbyaddr( ), gethostbyname( ), getipnodebyaddr( ), and getipnodebyname( ): 10329 HOST_NOT_FOUND 10330 NO_DATA 10331 NO_RECOVERY 10332 TRY_AGAIN 10333 The header shall define the following macros that evaluate to bitwise-distinct integer 10334 constants, for use in the flags argument of getipnodebyname( ): 10335 IP6 AI_V4MAPPED IPv4-mapped IPv6 addresses are acceptable. 10336 AI_ALL Return all addresses: IPv6 and IPv4-mapped IPv6. 10337 AI_ADDRCONFIG 10338 Return addresses depending on what source addresses are configured. 10339 The header shall define the AI_DEFAULT macro, which evaluates to the logical OR of 10340 AI_V4MAPPED and AI_ADDRCONFIG. | 10341 Address Information Structure 10342 The header shall define the addrinfo structure that includes at least the following 10343 members: 10344 int ai_flags Input flags. 10345 int ai_family Address family of socket. 10346 int ai_socktype Socket type. 10347 int ai_protocol Protocol of socket. 10348 socklen_t ai_addrlen Length of socket address. 10349 struct sockaddr *ai_addr Socket address of socket. 10350 char *ai_canonname Canonical name of service location. 10351 struct addrinfo *ai_next Pointer to next in list. 10352 The header shall define the following macros that evaluate to bitwise-distinct integer 10353 constants for use in the flags field of the addrinfo structure: 10354 AI_PASSIVE Socket address is intended for bind( ). 10355 AI_CANONNAME 10356 Request for canonical name. 10357 AI_NUMERICHOST 10358 Return numeric host address as name. 10359 The header shall define the following macros that evaluate to bitwise-distinct integer 10360 constants for use in the flags argument to getnameinfo( ): 10361 NI_NOFQDN Only the nodename portion of the FQDN is returned for local hosts. 10362 NI_NUMERICHOST 10363 The numeric form of the node's address is returned instead of its name. Base Definitions, Issue 6 311 Headers 10364 NI_NAMEREQD Return an error if the node's name cannot be located in the database. 10365 NI_NUMERICSERV 10366 The numeric form of the service address is returned instead of its name. 10367 NI_DGRAM Indicates that the service is a datagram service (SOCK_DGRAM). 10368 Address Information Errors 10369 The header shall define the following macros for use as error values for getaddrinfo( ) 10370 and getnameinfo( ): 10371 EAI_AGAIN The name could not be resolved at this time. Future attempts may succeed. 10372 EAI_BADFLAGS The flags had an invalid value. 10373 EAI_FAIL A non-recoverable error occurred. 10374 EAI_FAMILY The address family was not recognized or the address length was invalid for 10375 the specified family. 10376 EAI_MEMORY There was a memory allocation failure. 10377 EAI_NONAME The name does not resolve for the supplied parameters. 10378 NI_NAMEREQD is set and the host's name cannot be located, or both 10379 nodename and servname were null. 10380 EAI_SERVICE The service passed was not recognized for the specified socket type. 10381 EAI_SOCKTYPE The intended socket type was not recognized. 10382 EAI_SYSTEM A system error occurred. The error code can be found in errno. 10383 The following shall be declared as functions, and may also be defined as macros. Function | 10384 prototypes shall be provided for use with an ISO C standard compiler. | 10385 void endhostent(void); | 10386 void endnetent(void); | 10387 void endprotoent(void); | 10388 void endservent(void); | 10389 void freeaddrinfo(struct addrinfo *); | 10390 void freehostent(struct hostent *); | 10391 char *gai_strerror(int); | 10392 int getaddrinfo(const char *, const char *, | 10393 const struct addrinfo *, struct addrinfo **); | 10394 struct hostent *gethostbyaddr(const void *, socklen_t, int); | 10395 struct hostent *gethostbyname(const char *); | 10396 struct hostent *gethostent(void); | 10397 struct hostent *getipnodebyaddr(const void *restrict, socklen_t, int, | 10398 int *restrict); | 10399 struct hostent *getipnodebyname(const char *, int, int, int *); | 10400 int getnameinfo(const struct sockaddr *, socklen_t, | 10401 char *, socklen_t, char *, socklen_t, unsigned); | 10402 struct netent *getnetbyaddr(uint32_t, int); | 10403 struct netent *getnetbyname(const char *); | 10404 struct netent *getnetent(void); | 10405 struct protoent *getprotobyname(const char *); | 10406 struct protoent *getprotobynumber(int); | 10407 struct protoent *getprotoent(void); | 312 Technical Standard (2000) (Draft July 28, 2000) Headers 10408 struct servent *getservbyname(const char *, const char *); | 10409 struct servent *getservbyport(int, const char *); | 10410 struct servent *getservent(void); | 10411 void sethostent(int); | 10412 void setnetent(int); | 10413 void setprotoent(int); | 10414 void setservent(int); | 10415 The type socklen_t shall be defined through typedef as described in . | 10416 Inclusion of the header may also make visible all symbols from and | 10417 . | 10418 APPLICATION USAGE 10419 None. 10420 RATIONALE 10421 None. 10422 FUTURE DIRECTIONS 10423 None. 10424 SEE ALSO 10425 , , , the System Interfaces volume of | 10426 IEEE Std. 1003.1-200x, bind( ), endhostent( ), endnetent( ), endprotoent( ), endservent( ), getaddrinfo( ), 10427 getnameinfo( ) 10428 CHANGE HISTORY 10429 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. | 10430 The restrict keyword is added to the prototype for getipnodebyaddr( ). | Base Definitions, Issue 6 313 Headers 10431 NAME 10432 netinet/in.h - Internet protocol family 10433 SYNOPSIS 10434 #include 10435 DESCRIPTION 10436 The header shall define the following types through typedef: 10437 in_port_t An unsigned integer type of exactly 16 bits. | 10438 in_addr_t An unsigned integer type of exactly 32 bits. | 10439 The sa_family_t type shall be defined as described in . 10440 The uint32_t type shall be defined as described in . Inclusion of the | 10441 header may also make visible all symbols from . | 10442 The header shall define the in_addr structure that includes at least the following | 10443 member: 10444 in_addr_t s_addr 10445 The header shall define the sockaddr_in structure that includes at least the 10446 following members: 10447 sa_family_t sin_family 10448 in_port_t sin_port 10449 struct in_addr sin_addr 10450 unsigned char sin_zero[8] 10451 The sockaddr_in structure is used to store addresses for the Internet protocol family. Values of 10452 this type shall be cast by applications to struct sockaddr for use with socket functions. 10453 IP6 The header shall define the in6_addr structure that contains at least the following | 10454 member: | 10455 uint8_t s6_addr[16] | 10456 This array is used to contain a 128-bit IPv6 address, stored in network byte order. | 10457 The header shall define the sockaddr_in6 structure that includes at least the 10458 following members: 10459 sa_family_t sin6_family AF_INET6. 10460 in_port_t sin6_port Port number. 10461 uint32_t sin6_flowinfo IPv6 traffic class and flow information. 10462 struct in6_addr sin6_addr IPv6 address. 10463 uint32_t sin6_scope_id Set of interfaces for a scope. 10464 The sockaddr_in6 structure shall be set to zero by an application prior to using it, since 10465 implementations are free to have additional, implementation-defined fields in sockaddr_in6. | 10466 The sin6_scope_id field is a 32-bit integer that identifies a set of interfaces as appropriate for the 10467 scope of the address carried in the sin6_addr field. For a link scope sin6_addr, sin6_scope_id would 10468 be an interface index. For a site scope sin6_addr, sin6_scope_id would be a site identifier. The 10469 mapping of sin6_scope_id to an interface or set of interfaces is implementation-defined. | 10470 The header shall declare the following external variable: | 10471 struct in6_addr in6addr_any | 314 Technical Standard (2000) (Draft July 28, 2000) Headers 10472 This variable is initialized by the system to contain the wildcard IPv6 address. The | 10473 header also defines the IN6ADDR_ANY_INIT macro. This macro must be | 10474 constant at compile time and can be used to initialize a variable of type struct in6_addr to the | 10475 IPv6 wildcard address. 10476 The header shall declare the following external variable: | 10477 struct in6_addr in6addr_loopback | 10478 This variable is initialized by the system to contain the loopback IPv6 address. The | 10479 header also defines the IN6ADDR_LOOPBACK_INIT macro. This macro must be | 10480 constant at compile time and can be used to initialize a variable of type struct in6_addr to the | 10481 IPv6 loopback address. 10482 The header shall define the ipv6_mreq structure that includes at least the | 10483 following members: 10484 struct in6_addr ipv6mr_multiaddr IPv6 multicast address. 10485 unsigned ipv6mr_interface Interface index. 10486 10487 The header shall define the following macros for use as values of the level 10488 argument of getsockopt( ) and setsockopt( ): 10489 IPPROTO_IP Internet protocol. | 10490 IP6 IPPROTO_IPV6 Internet Protocol Version 6. | 10491 IPPROTO_ICMP Control message protocol. 10492 IPPROTO_TCP Transmission control protocol. 10493 IPPROTO_UDP User datagram protocol. 10494 The header shall define the following macros for use as destination addresses for 10495 connect( ), sendmsg( ), and sendto( ): 10496 INADDR_ANY IPv4 local host address. 10497 INADDR_BROADCAST IPv4 broadcast address. 10498 The header shall define the following macro to help applications declare buffers 10499 of the proper size to store IPv4 addresses in string form: 10500 INET_ADDRSTRLEN 16. 10501 The htonl( ), htons( ), ntohl( ), and ntohs( ) functions shall be available as defined in . 10502 Inclusion of the header may also make visible all symbols from . 10503 IP6 The header shall define the following macro to help applications declare buffers 10504 of the proper size to store IPv6 addresses in string form: 10505 INET6_ADDRSTRLEN 46. 10506 The header shall define the following macros, with distinct integral values, for 10507 use in the option_name argument in the getsockopt( ) or setsockopt( ) functions at protocol level 10508 IPPROTO_IPV6: 10509 IPV6_JOIN_GROUP Join a multicast group. 10510 IPV6_LEAVE_GROUP Quit a multicast group. Base Definitions, Issue 6 315 Headers 10511 IPV6_MULTICAST_HOPS 10512 Multicast hop limit. 10513 IPV6_MULTICAST_IF Interface to use for outgoing multicast packets. 10514 IPV6_MULTICAST_LOOP 10515 Multicast packets are delivered back to the local application. 10516 IPV6_UNICAST_HOPS Unicast hop limit. 10517 The header shall define the following macros that test for special IPv6 addresses. 10518 Each macro is of type int and takes a single argument of type const struct in6_addr *: 10519 IN6_IS_ADDR_UNSPECIFIED 10520 Unspecified address. 10521 IN6_IS_ADDR_LOOPBACK 10522 Loopback address. 10523 IN6_IS_ADDR_MULTICAST 10524 Multicast address. 10525 IN6_IS_ADDR_LINKLOCAL 10526 Unicast link-local address. 10527 IN6_IS_ADDR_SITELOCAL 10528 Unicast site-local address. 10529 IN6_IS_ADDR_V4MAPPED 10530 IPv4 mapped address. 10531 IN6_IS_ADDR_V4COMPAT 10532 IPv4-compatible address. 10533 IN6_IS_ADDR_MC_NODELOCAL 10534 Multicast node-local address. 10535 IN6_IS_ADDR_MC_LINKLOCAL 10536 Multicast link-local address. 10537 IN6_IS_ADDR_MC_SITELOCAL 10538 Multicast site-local address. 10539 IN6_IS_ADDR_MC_ORGLOCAL 10540 Multicast organization-local address. 10541 IN6_IS_ADDR_MC_GLOBAL 10542 Multicast global address. 10543 IN6_IS_ADDR_LINKLOCAL and IN6_IS_ADDR_SITELOCAL return true only for the two 10544 local-use IPv6 unicast addresses. They do not return true for multicast addresses of either link- 10545 local or site-local scope. 316 Technical Standard (2000) (Draft July 28, 2000) Headers 10546 APPLICATION USAGE 10547 None. 10548 RATIONALE 10549 None. 10550 FUTURE DIRECTIONS 10551 None. 10552 SEE ALSO 10553 , , , the System Interfaces volume of | 10554 IEEE Std. 1003.1-200x, connect( ), getsockopt( ), htonl( ), htons( ), ntohl( ), ntohs( ), sendmsg( ), 10555 sendto( ), setsockopt( ) 10556 CHANGE HISTORY 10557 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. | Base Definitions, Issue 6 317 Headers 10558 NAME 10559 netinet/tcp.h - definitions for the Internet Transmission Control Protocol (TCP) 10560 SYNOPSIS 10561 #include 10562 DESCRIPTION 10563 The header shall define the following macro for use as a socket option at the 10564 IPPROTO_TCP level: 10565 TCP_NODELAY Avoid coalescing of small segments. 10566 The macro shall be defined in the header. The implementation need not allow the value of the 10567 option to be set via setsockopt( ) or retrieved via getsockopt( ). 10568 APPLICATION USAGE 10569 None. 10570 RATIONALE 10571 None. 10572 FUTURE DIRECTIONS 10573 None. 10574 SEE ALSO 10575 , the System Interfaces volume of IEEE Std. 1003.1-200x, getsockopt( ), setsockopt( ) 10576 CHANGE HISTORY 10577 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. | 318 Technical Standard (2000) (Draft July 28, 2000) Headers 10578 NAME 10579 nl_types.h - data types 10580 SYNOPSIS 10581 XSI #include 10582 10583 DESCRIPTION 10584 The header shall contain definitions of at least the following types: 10585 nl_catd Used by the message catalog functions catopen( ), catgets( ), and catclose( ) 10586 to identify a catalog descriptor. 10587 nl_item Used by nl_langinfo ( ) to identify items of langinfo data. Values of objects 10588 of type nl_item are defined in . 10589 The header shall contain definitions of at least the following constants: 10590 NL_SETD Used by gencat when no $set directive is specified in a message text source | 10591 file; see the Internationalization Guide. This constant can be passed as the | 10592 value of set_id on subsequent calls to catgets( ) (that is, to retrieve | 10593 messages from the default message set). The value of NL_SETD is | 10594 implementation-defined. | 10595 NL_CAT_LOCALE Value that must be passed as the oflag argument to catopen( ) to ensure 10596 that message catalog selection depends on the LC_MESSAGES locale 10597 category, rather than directly on the LANG environment variable. 10598 The following shall be declared as functions and may also be defined as macros. Function 10599 prototypes shall be provided for use with an ISO C standard compiler. 10600 int catclose(nl_catd); 10601 char *catgets(nl_catd, int, int, const char *); 10602 nl_catd catopen(const char *, int); 10603 APPLICATION USAGE 10604 None. 10605 RATIONALE 10606 None. 10607 FUTURE DIRECTIONS 10608 None. 10609 SEE ALSO 10610 , the System Interfaces volume of IEEE Std. 1003.1-200x, catclose( ), catgets( ), 10611 catopen( ), nl_langinfo ( ), the Shell and Utilities volume of IEEE Std. 1003.1-200x, gencat | 10612 CHANGE HISTORY 10613 First released in Issue 2. 10614 Issue 4 10615 The following change is incorporated for alignment with the ISO C standard: 10616 * The function declarations in this header are expanded to full ISO C standard prototypes. Base Definitions, Issue 6 319 Headers 10617 NAME 10618 poll.h - definitions for the poll( ) function 10619 SYNOPSIS 10620 XSI #include 10621 10622 DESCRIPTION 10623 The header shall define the pollfd structure that includes at least the following 10624 members: 10625 int fd The following descriptor being polled. 10626 short events The input event flags (see below). 10627 short revents The output event flags (see below). 10628 The header shall define the following type through typedef: 10629 nfds_t An unsigned integer type used for the number of file descriptors. | 10630 The following symbolic constants shall be defined, zero or more of which may be OR'ed together 10631 to form the events or revents members in the pollfd structure: 10632 POLLIN Same effect as POLLRDNORM | POLLRDBAND. 10633 POLLRDNORM Data on priority band 0 may be read. 10634 POLLRDBAND Data on priority bands greater than 0 may be read. 10635 POLLPRI High priority data may be read. 10636 POLLOUT Same value as POLLWRNORM. 10637 POLLWRNORM Data on priority band 0 may be written. 10638 POLLWRBAND Data on priority bands greater than 0 may be written. This event only 10639 examines bands that have been written to at least once. 10640 POLLERR An error has occurred (revents only). 10641 POLLHUP Device has been disconnected (revents only). 10642 POLLNVAL Invalid fd member (revents only). 10643 The header shall declare the following function which may also be defined as a macro. 10644 Function prototypes shall be provided for use with an ISO C standard compiler. 10645 int poll(struct pollfd[], nfds_t, int); 10646 APPLICATION USAGE 10647 None. 10648 RATIONALE 10649 None. 10650 FUTURE DIRECTIONS 10651 None. 10652 SEE ALSO 10653 The System Interfaces volume of IEEE Std. 1003.1-200x, poll( ) 320 Technical Standard (2000) (Draft July 28, 2000) Headers 10654 CHANGE HISTORY 10655 First released in Issue 4, Version 2. Base Definitions, Issue 6 321 Headers 10656 NAME 10657 pthread.h - threads 10658 SYNOPSIS 10659 THR #include 10660 10661 DESCRIPTION 10662 The header shall define the following symbols: 10663 BAR PTHREAD_BARRIER_SERIAL_THREAD | 10664 PTHREAD_CANCEL_ASYNCHRONOUS | 10665 PTHREAD_CANCEL_ENABLE 10666 PTHREAD_CANCEL_DEFERRED 10667 PTHREAD_CANCEL_DISABLE 10668 PTHREAD_CANCELED 10669 PTHREAD_COND_INITIALIZER 10670 PTHREAD_CREATE_DETACHED 10671 PTHREAD_CREATE_JOINABLE 10672 PTHREAD_EXPLICIT_SCHED 10673 PTHREAD_INHERIT_SCHED 10674 XSI PTHREAD_MUTEX_DEFAULT 10675 PTHREAD_MUTEX_ERRORCHECK 10676 PTHREAD_MUTEX_INITIALIZER 10677 XSI PTHREAD_MUTEX_NORMAL 10678 PTHREAD_MUTEX_RECURSIVE 10679 PTHREAD_ONCE_INIT 10680 TPP|TPI PTHREAD_PRIO_INHERIT 10681 PTHREAD_PRIO_NONE 10682 PTHREAD_PRIO_PROTECT 10683 PTHREAD_PROCESS_SHARED 10684 PTHREAD_PROCESS_PRIVATE 10685 TPS PTHREAD_SCOPE_PROCESS 10686 PTHREAD_SCOPE_SYSTEM 10687 10688 The following types shall be defined as described in : | 10689 pthread_attr_t | 10690 BAR pthread_barrier_t 10691 pthread_barrierattr_t 10692 pthread_cond_t | 10693 pthread_condattr_t 10694 pthread_key_t 10695 pthread_mutex_t 10696 pthread_mutexattr_t 10697 pthread_once_t 10698 pthread_rwlock_t | 10699 pthread_rwlockattr_t 10700 SPI pthread_spinlock_t 10701 pthread_t | 10702 The following shall be declared as functions and may also be declared as macros. Function | 10703 prototypes shall be provided for use with an ISO C standard compiler. 322 Technical Standard (2000) (Draft July 28, 2000) Headers 10704 int pthread_atfork(void (*)(void), void (*)(void), 10705 void(*)(void)); 10706 int pthread_attr_destroy(pthread_attr_t *); 10707 int pthread_attr_getdetachstate(const pthread_attr_t *, int *); 10708 XSI int pthread_attr_getguardsize(const pthread_attr_t *restrict, 10709 size_t *restrict); 10710 TPS int pthread_attr_getinheritsched(const pthread_attr_t *restrict, 10711 int *restrict); 10712 int pthread_attr_getschedparam(const pthread_attr_t *restrict, 10713 struct sched_param *restrict); 10714 TPS int pthread_attr_getschedpolicy(const pthread_attr_t *restrict, 10715 int *restrict); 10716 TPS int pthread_attr_getscope(const pthread_attr_t *restrict, 10717 int *restrict); 10718 TSA int pthread_attr_getstackaddr(const pthread_attr_t *restrict, 10719 void **restrict); 10720 int pthread_attr_getstacksize(const pthread_attr_t *restrict, 10721 size_t *restrict); 10722 int pthread_attr_init(pthread_attr_t *); 10723 int pthread_attr_setdetachstate(pthread_attr_t *, int); 10724 XSI int pthread_attr_setguardsize(pthread_attr_t *, size_t); 10725 TPS int pthread_attr_setinheritsched(pthread_attr_t *, int); 10726 int pthread_attr_setschedparam(pthread_attr_t *restrict, 10727 const struct sched_param *restrict); 10728 TPS int pthread_attr_setschedpolicy(pthread_attr_t *, int); 10729 int pthread_attr_setscope(pthread_attr_t *, int); 10730 TSA int pthread_attr_setstackaddr(pthread_attr_t *, void *); 10731 int pthread_attr_setstacksize(pthread_attr_t *, size_t); 10732 BAR int pthread_barrier_destroy(pthread_barrier_t *); 10733 int pthread_barrier_init(pthread_barrier_t *restrict, 10734 const pthread_barrierattr_t *restrict, unsigned); 10735 int pthread_barrier_wait(pthread_barrier_t *); 10736 int pthread_barrierattr_destroy(pthread_barrierattr_t *); 10737 int pthread_barrierattr_getpshared(const pthread_barrierattr_t *restrict, 10738 int *restrict); 10739 int pthread_barrierattr_init(pthread_barrierattr_t *); 10740 int pthread_barrierattr_setpshared(pthread_barrierattr_t *, int); 10741 int pthread_cancel(pthread_t); 10742 void pthread_cleanup_push(void (*)(void *), void *); 10743 void pthread_cleanup_pop(int); 10744 int pthread_cond_broadcast(pthread_cond_t *); 10745 int pthread_cond_destroy(pthread_cond_t *); 10746 int pthread_cond_init(pthread_cond_t *restrict, 10747 const pthread_condattr_t *restrict); 10748 int pthread_cond_signal(pthread_cond_t *); 10749 int pthread_cond_timedwait(pthread_cond_t *restrict, 10750 pthread_mutex_t *restrict, const struct timespec *restrict); 10751 int pthread_cond_wait(pthread_cond_t *restrict, 10752 pthread_mutex_t *restrict); 10753 int pthread_condattr_destroy(pthread_condattr_t *); 10754 CS int pthread_condattr_getclock(const pthread_condattr_t *restrict, 10755 clockid_t *restrict); Base Definitions, Issue 6 323 Headers 10756 int pthread_condattr_getpshared(const pthread_condattr_t *restrict, 10757 int *restrict); 10758 int pthread_condattr_init(pthread_condattr_t *); 10759 CS int pthread_condattr_setclock(pthread_condattr_t *, clockid_t); 10760 int pthread_condattr_setpshared(pthread_condattr_t *, int); 10761 int pthread_create(pthread_t *restrict, const pthread_attr_t *restrict, 10762 void *(*)(void *), void *); 10763 int pthread_detach(pthread_t); 10764 int pthread_equal(pthread_t, pthread_t); 10765 void pthread_exit(void *); 10766 XSI int pthread_getconcurrency(void); 10767 TCT int pthread_getcpuclockid(pthread_t, clockid_t *); 10768 TPS int pthread_getschedparam(pthread_t, int *restrict, 10769 struct sched_param *restrict); 10770 void *pthread_getspecific(pthread_key_t); 10771 int pthread_join(pthread_t, void **); 10772 int pthread_key_create(pthread_key_t *, void (*)(void *)); 10773 int pthread_key_delete(pthread_key_t); 10774 int pthread_kill(pthread_t, int); 10775 int pthread_mutex_destroy(pthread_mutex_t *); 10776 TPP int pthread_mutex_getprioceiling(const pthread_mutex_t *restrict, 10777 int *restrict); 10778 int pthread_mutex_init(pthread_mutex_t *restrict, 10779 const pthread_mutexattr_t *restrict); 10780 int pthread_mutex_lock(pthread_mutex_t *); 10781 TPP int pthread_mutex_setprioceiling(pthread_mutex_t *restrict, int, 10782 int *restrict); 10783 TMO int pthread_mutex_timedlock(pthread_mutex_t *, 10784 const struct timespec *); 10785 int pthread_mutex_trylock(pthread_mutex_t *); 10786 int pthread_mutex_unlock(pthread_mutex_t *); 10787 int pthread_mutexattr_destroy(pthread_mutexattr_t *); 10788 TPP|TPI int pthread_mutexattr_getprioceiling(const pthread_mutexattr_t *restrict, 10789 int *restrict); 10790 int pthread_mutexattr_getprotocol(const pthread_mutexattr_t *restrict, 10791 int *restrict); 10792 int pthread_mutexattr_getpshared(const pthread_mutexattr_t *restrict, 10793 int *restrict); 10794 XSI int pthread_mutexattr_gettype(const pthread_mutexattr_t *restrict, 10795 int *restrict); 10796 int pthread_mutexattr_init(pthread_mutexattr_t *); 10797 TPP|TPI int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *, int); 10798 int pthread_mutexattr_setprotocol(pthread_mutexattr_t *, int); 10799 int pthread_mutexattr_setpshared(pthread_mutexattr_t *, int); 10800 XSI int pthread_mutexattr_settype(pthread_mutexattr_t *, int); 10801 int pthread_once(pthread_once_t *, void (*)(void)); 10802 int pthread_rwlock_destroy(pthread_rwlock_t *); 10803 int pthread_rwlock_init(pthread_rwlock_t *restrict, 10804 const pthread_rwlockattr_t *restrict); 10805 int pthread_rwlock_rdlock(pthread_rwlock_t *); 10806 int pthread_rwlock_timedrdlock(pthread_rwlock_t *restrict, 10807 const struct timespec *restrict); 324 Technical Standard (2000) (Draft July 28, 2000) Headers 10808 int pthread_rwlock_timedwrlock(pthread_rwlock_t *restrict, 10809 const struct timespec *restrict); 10810 int pthread_rwlock_tryrdlock(pthread_rwlock_t *); 10811 int pthread_rwlock_trywrlock(pthread_rwlock_t *); 10812 int pthread_rwlock_unlock(pthread_rwlock_t *); 10813 int pthread_rwlock_wrlock(pthread_rwlock_t *); 10814 int pthread_rwlockattr_destroy(pthread_rwlockattr_t *); 10815 int pthread_rwlockattr_getpshared(const pthread_rwlockattr_t *restrict, 10816 int *restrict); 10817 int pthread_rwlockattr_init(pthread_rwlockattr_t *); 10818 int pthread_rwlockattr_setpshared(pthread_rwlockattr_t *, int); 10819 pthread_t 10820 pthread_self(void); 10821 int pthread_setcancelstate(int, int *); 10822 int pthread_setcanceltype(int, int *); 10823 XSI int pthread_setconcurrency(int); 10824 TPS int pthread_setschedparam(pthread_t, int, 10825 const struct sched_param *); 10826 int pthread_setspecific(pthread_key_t, const void *); 10827 int pthread_sigmask(int, const sigset_t *restrict, sigset_t *restrict); 10828 SPI int pthread_spin_destroy(pthread_spinlock_t *); 10829 int pthread_spin_init(pthread_spinlock_t *, int); 10830 int pthread_spin_lock(pthread_spinlock_t *); 10831 int pthread_spin_trylock(pthread_spinlock_t *); 10832 int pthread_spin_unlock(pthread_spinlock_t *); 10833 void pthread_testcancel(void); 10834 XSI Inclusion of the header shall make symbols defined in the headers and 10835 visible. 10836 APPLICATION USAGE 10837 An interpretation request has been filed with IEEE PASC concerning requirements for visibility 10838 of symbols in this header. 10839 RATIONALE 10840 None. 10841 FUTURE DIRECTIONS 10842 None. 10843 SEE ALSO 10844 , , the System Interfaces volume of IEEE Std. 1003.1-200x, 10845 pthread_attr_getguardsize( ), pthread_attr_init( ), pthread_attr_setscope( ), pthread_barrier_destroy( ), 10846 pthread_barrier_init( ), pthread_barrier_wait( ), pthread_barrierattr_destroy( ), 10847 pthread_barrierattr_getpshared( ), pthread_barrierattr_init( ), pthread_barrierattr_setpshared( ), 10848 pthread_cancel( ), pthread_cleanup_pop( ), pthread_cond_init( ), pthread_cond_signal( ), 10849 pthread_cond_wait( ), pthread_condattr_getclock( ), pthread_condattr_init( ), 10850 pthread_condattr_setclock( ), pthread_create( ), pthread_detach( ), pthread_equal( ), pthread_exit( ), 10851 pthread_getconcurrency( ), pthread_getcpuclockid( ), pthread_getschedparam( ), pthread_join( ), 10852 pthread_key_create( ), pthread_key_delete( ), pthread_mutex_init( ), pthread_mutex_lock( ), 10853 pthread_mutex_setprioceiling( ), pthread_mutex_timedlock( ), pthread_mutexattr_init( ), 10854 pthread_mutexattr_gettype( ), pthread_mutexattr_setprotocol( ), pthread_once( ), 10855 pthread_rwlock_destroy( ), pthread_rwlock_init( ), pthread_rwlock_rdlock( ), 10856 pthread_rwlock_timedrdlock( ), pthread_rwlock_timedwrlock( ), pthread_rwlock_tryrdlock( ), 10857 pthread_rwlock_trywrlock( ), pthread_rwlock_unlock( ), pthread_rwlock_wrlock( ), Base Definitions, Issue 6 325 Headers 10858 pthread_rwlockattr_destroy( ), pthread_rwlockattr_getpshared( ), pthread_rwlockattr_init( ), 10859 pthread_rwlockattr_setpshared( ), pthread_self( ), pthread_setcancelstate( ), pthread_setspecific( ), 10860 pthread_spin_destroy( ), pthread_spin_init( ), pthread_spin_lock( ), pthread_spin_trylock( ), 10861 pthread_spin_unlock( ) 10862 CHANGE HISTORY 10863 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 10864 Issue 6 10865 The RTT margin markers are now broken out into their POSIX options. 10866 The Open Group corrigenda item U021/9 has been applied, correcting the prototype for the 10867 pthread_cond_wait( ) function. 10868 The Open Group corrigenda item U026/2 has been applied correcting the prototype for the 10869 pthread_setschedparam( ) function so that its second argument is of type int. 10870 The pthread_getcpuclockid( ) and pthread_mutex_timedlock( ) functions are added for alignment 10871 with IEEE Std. 1003.1d-1999. 10872 The following functions are added for alignment with IEEE Std. 1003.1j-2000: 10873 pthread_barrier_destroy( ), pthread_barrier_init( ), pthread_barrier_wait( ), 10874 pthread_barrierattr_destroy( ), pthread_barrierattr_getpshared( ), pthread_barrierattr_init( ), 10875 pthread_barrierattr_setpshared( ), pthread_condattr_getclock( ), pthread_condattr_setclock( ), 10876 pthread_rwlock_timedrdlock( ), pthread_rwlock_timedwrlock( ), pthread_spin_destroy( ), 10877 pthread_spin_init( ), pthread_spin_lock( ), pthread_spin_trylock( ), and pthread_spin_unlock( ). 10878 PTHREAD_RWLOCK_INITIALIZER is deleted for alignment with IEEE Std. 1003.1j-2000. | 10879 Functions previously marked as part of the Read-Write Locks option are now moved to the | 10880 Threads option. | 10881 The restrict keyword is added to the prototypes for pthread_attr_getguardsize( ), | 10882 pthread_attr_getinheritsched( ), pthread_attr_getschedparam( ), pthread_attr_getschedpolicy( ), | 10883 pthread_attr_getscope( ), pthread_attr_getstackaddr( ), pthread_attr_getstacksize( ), | 10884 pthread_attr_setschedparam( ), pthread_barrier_init( ), pthread_barrierattr_getpshared( ), | 10885 pthread_cond_init( ), pthread_cond_signal( ), pthread_cond_timedwait( ), pthread_cond_wait( ), | 10886 pthread_condattr_getclock( ), pthread_condattr_getpshared( ), pthread_create( ), | 10887 pthread_getschedparam( ), pthread_mutex_getprioceiling( ), pthread_mutex_init( ), | 10888 pthread_mutex_setprioceiling( ), pthread_mutexattr_getprioceiling( ), pthread_mutexattr_getprotocol( ), | 10889 pthread_mutexattr_getpshared( ), pthread_mutexattr_gettype( ), pthread_rwlock_init( ), | 10890 pthread_rwlock_timedrdlock( ), pthread_rwlock_timedwrlock( ), pthread_rwlockattr_getpshared( ), and | 10891 pthread_sigmask( ). | 326 Technical Standard (2000) (Draft July 28, 2000) Headers 10892 NAME 10893 pwd.h - password structure 10894 SYNOPSIS 10895 #include 10896 DESCRIPTION 10897 The header shall provide a definition for struct passwd, which shall include at least the 10898 following members: 10899 char *pw_name User's login name. 10900 uid_t pw_uid Numerical user ID. 10901 gid_t pw_gid Numerical group ID. 10902 char *pw_dir Initial working directory. 10903 char *pw_shell Program to use as shell. 10904 The gid_t and uid_t types shall be defined as described in . | 10905 The following shall be declared as functions and may also be defined as macros. Function 10906 prototypes shall be provided for use with an ISO C standard compiler. 10907 struct passwd *getpwnam(const char *); 10908 struct passwd *getpwuid(uid_t); 10909 TSF int getpwnam_r(const char *, struct passwd *, char *, 10910 size_t, struct passwd **); 10911 int getpwuid_r(uid_t, struct passwd *, char *, 10912 size_t, struct passwd **); 10913 XSI void endpwent(void); 10914 struct passwd *getpwent(void); 10915 void setpwent(void); 10916 10917 APPLICATION USAGE 10918 None. 10919 RATIONALE 10920 None. 10921 FUTURE DIRECTIONS 10922 None. 10923 SEE ALSO 10924 , the System Interfaces volume of IEEE Std. 1003.1-200x, endpwent( ), getpwnam( ), 10925 getpwuid( ) 10926 CHANGE HISTORY 10927 First released in Issue 1. 10928 Issue 4 10929 Reference to the header is added for the definitions of gid_t and uid_t. This is 10930 marked as an extension. 10931 The following change is incorporated for alignment with the ISO POSIX-1 standard: 10932 * The function declarations in this header are expanded to full ISO C standard prototypes. Base Definitions, Issue 6 327 Headers 10933 Issue 4, Version 2 10934 For X/OPEN UNIX conformance, the getpwent( ), endpwent( ), and setpwent( ) functions are added 10935 to the list of functions declared in this header. 10936 Issue 5 10937 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 10938 Issue 6 10939 The following new requirements on POSIX implementations derive from alignment with the 10940 Single UNIX Specification: 10941 * The gid_t and uid_t types are mandated. 10942 * The getpwnam_r( ) and getpwuid_r( ) functions are marked as part of the 10943 _POSIX_THREAD_SAFE_FUNCTIONS option. 328 Technical Standard (2000) (Draft July 28, 2000) Headers 10944 NAME 10945 regex.h - regular expression matching types 10946 SYNOPSIS 10947 #include 10948 DESCRIPTION 10949 The header shall define the structures and symbolic constants used by the regcomp( ), 10950 regexec( ), regerror( ), and regfree( ) functions. 10951 The structure type regex_t shall contain at least the following member: 10952 size_t re_nsub Number of parenthesized subexpressions. 10953 The type regoff_t shall be defined as a signed arithmetic type that can hold the largest value that 10954 can be stored in either a type off_t or type ssize_t. The structure type regmatch_t shall contain 10955 at least the following members: 10956 regoff_t rm_so Byte offset from start of string 10957 to start of substring. 10958 regoff_t rm_eo Byte offset from start of string of the 10959 first character after the end of substring. 10960 Values for the cflags parameter to the regcomp( ) function: 10961 REG_EXTENDED Use Extended Regular Expressions. 10962 REG_ICASE Ignore case in match. 10963 REG_NOSUB Report only success or fail in regexec( ). 10964 REG_NEWLINE Change the handling of newline. 10965 Values for the eflags parameter to the regexec( ) function: 10966 REG_NOTBOL The circumflex character (' '), when taken as a special character, does 10967 not match the beginning of string. 10968 REG_NOTEOL The dollar sign ('$'), when taken as a special character, does not match 10969 the end of string. 10970 The following constants shall be defined as error return values: 10971 REG_NOMATCH regexec( ) failed to match. 10972 REG_BADPAT Invalid regular expression. 10973 REG_ECOLLATE Invalid collating element referenced. 10974 REG_ECTYPE Invalid character class type referenced. 10975 REG_EESCAPE Trailing '\' in pattern. 10976 REG_ESUBREG Number in \digit invalid or in error. 10977 REG_EBRACK "[]" imbalance. 10978 REG_EPAREN "\(\)" or "()" imbalance. 10979 REG_EBRACE "\{\}" imbalance. 10980 REG_BADBR Content of "\{\}" invalid: not a number, number too large, more than 10981 two numbers, first larger than second. Base Definitions, Issue 6 329 Headers 10982 REG_ERANGE Invalid endpoint in range expression. 10983 REG_ESPACE Out of memory. 10984 REG_BADRPT '?', '*', or '+' not preceded by valid regular expression. 10985 REG_ENOSYS The implementation does not support the function. (LEGACY) | 10986 The following shall be declared as functions and may also be declared as macros. Function 10987 prototypes shall be provided for use with an ISO C standard compiler. 10988 int regcomp(regex_t *restrict, const char *restrict, int); 10989 size_t regerror(int, const regex_t *restrict, char *restrict, size_t); 10990 int regexec(const regex_t *restrict, const char *restrict, size_t, 10991 regmatch_t[restrict], int); 10992 void regfree(regex_t *); 10993 The implementation may define additional macros or constants using names beginning with 10994 REG_. 10995 APPLICATION USAGE 10996 None. 10997 RATIONALE 10998 None. 10999 FUTURE DIRECTIONS 11000 None. 11001 SEE ALSO 11002 The System Interfaces volume of IEEE Std. 1003.1-200x, regcomp( ), the Shell and Utilities volume | 11003 of IEEE Std. 1003.1-200x | 11004 CHANGE HISTORY 11005 First released in Issue 4. 11006 Originally derived from the ISO POSIX-2 standard. | 11007 Issue 6 | 11008 The REG_ENOSYS constant is marked LEGACY. | 11009 The restrict keyword is added to the prototypes for regcomp( ), regerror( ), and regexec( ). | 330 Technical Standard (2000) (Draft July 28, 2000) Headers 11010 NAME 11011 sched.h - execution scheduling (REALTIME) 11012 SYNOPSIS 11013 PS #include 11014 11015 DESCRIPTION 11016 The header shall define the sched_param structure, which contains the scheduling 11017 parameters required for implementation of each supported scheduling policy. This structure 11018 shall contain at least the following member: 11019 int sched_priority Process execution scheduling priority. 11020 SS|TSP In addition, if _POSIX_SPORADIC_SERVER or _POSIX_THREAD_SPORADIC_SERVER is 11021 defined, the sched_param structure defined in shall contain the following members 11022 in addition to those specified above: 11023 int sched_ss_low_priority Low scheduling priority for 11024 sporadic server. 11025 struct timespec sched_ss_repl_period Replenishment period for 11026 sporadic server. 11027 struct timespec sched_ss_init_budget Initial budget for sporadic server. 11028 int sched_ss_max_repl Maximum pending replenishments for 11029 sporadic server. 11030 11031 Each process is controlled by an associated scheduling policy and priority. Associated with each 11032 policy is a priority range. Each policy definition specifies the minimum priority range for that 11033 policy. The priority ranges for each policy may overlap the priority ranges of other policies. 11034 Four scheduling policies are defined; others may be defined by the implementation. The four 11035 standard policies are indicated by the values of the following symbolic constants: 11036 SCHED_FIFO First in-first out (FIFO) scheduling policy. 11037 SCHED_RR Round robin scheduling policy. | 11038 SS|TSP SCHED_SPORADIC Sporadic server scheduling policy. | 11039 SCHED_OTHER Another scheduling policy. 11040 The values of these constants are distinct. 11041 The following shall be declared as functions and may also be declared as macros. Function 11042 prototypes shall be provided for use with an ISO C standard compiler. 11043 int sched_get_priority_max(int); 11044 int sched_get_priority_min(int); 11045 int sched_getparam(pid_t, struct sched_param *); 11046 int sched_getscheduler(pid_t); 11047 int sched_rr_get_interval(pid_t, struct timespec *); 11048 int sched_setparam(pid_t, const struct sched_param *); 11049 int sched_setscheduler(pid_t, int, const struct sched_param *); 11050 int sched_yield(void); 11051 Inclusion of the header makes symbols defined in the header visible. Base Definitions, Issue 6 331 Headers 11052 APPLICATION USAGE 11053 None. 11054 RATIONALE 11055 None. 11056 FUTURE DIRECTIONS 11057 None. 11058 SEE ALSO 11059 11060 CHANGE HISTORY 11061 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 11062 Issue 6 11063 The header is marked as part of the Process Scheduling option. | 11064 Sporadic server members are added to the sched_param structure, and the SCHED_SPORADIC 11065 scheduling policy is added for alignment with IEEE Std. 1003.1d-1999. | 11066 IEEE PASC Interpretation 1003.1 #108 is applied, correcting the sched_param structure whose | 11067 members sched_ss_repl_period and sched_ss_init_budget members should be type struct timespec | 11068 and not timespec. | 332 Technical Standard (2000) (Draft July 28, 2000) Headers 11069 NAME 11070 search.h - search tables 11071 SYNOPSIS 11072 XSI #include 11073 11074 DESCRIPTION 11075 The header shall provide a type definition, ENTRY, for structure entry which shall 11076 include the following members: 11077 char *key 11078 void *data 11079 and shall define ACTION and VISIT as enumeration data types through type definitions as 11080 follows: 11081 enum { FIND, ENTER } ACTION; 11082 enum { preorder, postorder, endorder, leaf } VISIT; 11083 The size_t type shall be defined as described in . 11084 Each of the following shall be declared as a function, or defined as a macro, or both. Function 11085 prototypes shall be provided for use with an ISO C standard compiler. 11086 int hcreate(size_t); 11087 void hdestroy(void); 11088 ENTRY *hsearch(ENTRY, ACTION); 11089 void insque(void *, void *); 11090 void *lfind(const void *, const void *, size_t *, 11091 size_t, int (*)(const void *, const void *)); 11092 void *lsearch(const void *, void *, size_t *, 11093 size_t, int (*)(const void *, const void *)); 11094 void remque(void *); 11095 void *tdelete(const void *restrict, void **restrict, 11096 int(*)(const void *, const void *)); 11097 void *tfind(const void *, void *const *, 11098 int(*)(const void *, const void *)); 11099 void *tsearch(const void *, void **, 11100 int(*)(const void *, const void *)); 11101 void twalk(const void *, 11102 void (*)(const void *, VISIT, int )); 11103 APPLICATION USAGE 11104 None. 11105 RATIONALE 11106 None. 11107 FUTURE DIRECTIONS 11108 None. 11109 SEE ALSO 11110 , the System Interfaces volume of IEEE Std. 1003.1-200x, hcreate( ), insque( ), 11111 lsearch( ), remque( ), tsearch( ) Base Definitions, Issue 6 333 Headers 11112 CHANGE HISTORY 11113 First released in Issue 1. Derived from Issue 1 of the SVID. | 11114 Issue 4 11115 The function declarations in this header are expanded to full ISO C standard prototypes. 11116 Reference to the header is added for the definition of size_t. 11117 Issue 4, Version 2 11118 For X/OPEN UNIX conformance, the insque( ) and remque( ) functions are added to the list of 11119 functions declared in this header. 11120 Issue 6 11121 The Open Group corrigenda item U021/6 has been applied updating the prototypes for tdelete( ) 11122 and tsearch( ). | 11123 The restrict keyword is added to the prototype for tdelete( ). | 334 Technical Standard (2000) (Draft July 28, 2000) Headers 11124 NAME 11125 semaphore.h - semaphores (REALTIME) 11126 SYNOPSIS 11127 SEM #include 11128 11129 DESCRIPTION 11130 The header shall define the sem_t type, used in performing semaphore 11131 operations. The semaphore may be implemented using a file descriptor, in which case 11132 applications are able to open up at least a total of {OPEN_MAX} files and semaphores. The 11133 symbol SEM_FAILED shall be defined (see sem_open( )). 11134 The following shall be declared as functions and may also be declared as macros. Function 11135 prototypes shall be provided for use with an ISO C standard compiler. 11136 int sem_close(sem_t *); 11137 int sem_destroy(sem_t *); 11138 int sem_getvalue(sem_t *restrict, int *restrict); 11139 int sem_init(sem_t *, int, unsigned); 11140 sem_t *sem_open(const char *, int, ...); 11141 int sem_post(sem_t *); 11142 TMO int sem_timedwait(sem_t *restrict, const struct timespec *restrict); 11143 int sem_trywait(sem_t *); 11144 int sem_unlink(const char *); 11145 int sem_wait(sem_t *); 11146 Inclusion of the header may make visible symbols defined in the headers 11147 and . 11148 APPLICATION USAGE 11149 None. 11150 RATIONALE 11151 None. 11152 FUTURE DIRECTIONS 11153 None. 11154 SEE ALSO 11155 , , the System Interfaces volume of IEEE Std. 1003.1-200x, sem_destroy( ), 11156 sem_getvalue( ), sem_init( ), sem_open( ), sem_post( ), sem_timedwait( ), sem_trywait( ), sem_unlink( ), 11157 sem_wait( ) 11158 CHANGE HISTORY 11159 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 11160 Issue 6 11161 The header is marked as part of the Semaphores option. | 11162 The Open Group corrigenda item U021/3 has been applied, adding a description of 11163 SEM_FAILED. 11164 The sem_timedwait( ) function is added for alignment with IEEE Std. 1003.1d-1999. | 11165 The restrict keyword is added to the prototypes for sem_getvalue( ) and sem_timedwait( ). | Base Definitions, Issue 6 335 Headers 11166 NAME 11167 setjmp.h - stack environment declarations 11168 SYNOPSIS 11169 #include 11170 DESCRIPTION 11171 CX The functionality described on this reference page extends the ISO C standard. Applications 11172 shall define the appropriate feature test macro (see the System Interfaces volume of 11173 IEEE Std. 1003.1-200x, Section 2.2, The Compilation Environment) to enable the visibility of 11174 symbols in this header. 11175 The header shall contain the type definitions for array types jmp_buf and 11176 sigjmp_buf. 11177 The following shall be declared as functions and may also be defined as macros. Function 11178 prototypes shall be provided for use with an ISO C standard compiler. 11179 void longjmp(jmp_buf, int); 11180 void siglongjmp(sigjmp_buf, int); 11181 XSI void _longjmp(jmp_buf, int); 11182 11183 Each of the following may be declared as a function, or defined as a macro, or both. Function 11184 prototypes shall be provided for use with an ISO C standard compiler. 11185 int setjmp(jmp_buf); 11186 int sigsetjmp(sigjmp_buf, int); 11187 XSI int _setjmp(jmp_buf); 11188 11189 APPLICATION USAGE 11190 None. 11191 RATIONALE 11192 None. 11193 FUTURE DIRECTIONS 11194 None. 11195 SEE ALSO 11196 The System Interfaces volume of IEEE Std. 1003.1-200x, longjmp( ), _longjmp( ), setjmp( ), 11197 siglongjmp( ), sigsetjmp( ) 11198 CHANGE HISTORY 11199 First released in Issue 1. 11200 Issue 4 11201 The following changes are incorporated for alignment with the ISO C standard: 11202 * The function declarations in this header are expanded to full ISO C standard prototypes. 11203 * The DESCRIPTION is changed to indicate that all functions in this header can also be 11204 declared as macros. 11205 * The arguments jmp_buf and sigjmp_buf are specified as array types. 336 Technical Standard (2000) (Draft July 28, 2000) Headers 11206 Issue 4, Version 2 11207 For X/OPEN UNIX conformance, the _longjmp( ) and _setjmp( ) functions are added to the list of 11208 functions declared in this header. Base Definitions, Issue 6 337 Headers 11209 NAME 11210 signal.h - signals 11211 SYNOPSIS 11212 #include 11213 DESCRIPTION 11214 CX The functionality described on this reference page extends the ISO C standard. Applications 11215 shall define the appropriate feature test macro (see the System Interfaces volume of 11216 IEEE Std. 1003.1-200x, Section 2.2, The Compilation Environment) to enable the visibility of 11217 symbols in this header. 11218 The header shall define the following symbolic constants, each of which expands to a 11219 distinct constant expression of the type: 11220 void (*)(int) 11221 whose value matches no declarable function. 11222 SIG_DFL Request for default signal handling. 11223 SIG_ERR Return value from signal( ) in case of error. 11224 SIG_HOLD Request that signal be held. 11225 SIG_IGN Request that signal be ignored. 11226 The following data types shall be defined through typedef: 11227 sig_atomic_t Possibly volatile-qualified integer type of an object that can be accessed as | 11228 an atomic entity, even in the presence of asynchronous interrupts. | 11229 sigset_t Integer or structure type of an object used to represent sets of signals. | 11230 pid_t As described in . | 11231 RTS The header shall define the sigevent structure, which has at least the following 11232 members: 11233 int sigev_notify Notification type. 11234 int sigev_signo Signal number. 11235 union sigval sigev_value Signal value. 11236 void(*)(union sigval) sigev_notify_function Notification function. 11237 (pthread_attr_t *) sigev_notify_attributes Notification attributes. 11238 The following values of sigev_notify shall be defined: 11239 SIGEV_NONE No asynchronous notification is delivered when the event of interest 11240 occurs. 11241 SIGEV_SIGNAL A queued signal, with an application-defined value, is generated when 11242 the event of interest occurs. 11243 SIGEV_THREAD A notification function is called to perform notification. 11244 The sigval union shall be defined as: 11245 int sival_int Integer signal value. 11246 void *sival_ptr Pointer signal value. 11247 This header shall also declare the macros SIGRTMIN and SIGRTMAX, which evaluate to 11248 integral expressions and, if the Realtime Signals Extension option is supported, specify a range 11249 of signal numbers that are reserved for application use and for which the realtime signal 338 Technical Standard (2000) (Draft July 28, 2000) Headers 11250 behavior specified in this volume of IEEE Std. 1003.1-200x is supported. The signal numbers in 11251 this range do not overlap any of the signals specified in the following table. 11252 The range SIGRTMIN through SIGRTMAX inclusive shall include at least {RTSIG_MAX} signal 11253 numbers. 11254 It is implementation-defined whether realtime signal behavior is supported for other signals. | 11255 This header also declares the constants that are used to refer to the signals that occur in the 11256 system. Signals defined here begin with the letters SIG. Each of the signals have distinct positive 11257 integral values. The value 0 is reserved for use as the null signal (see kill( )). Additional | 11258 implementation-defined signals may occur in the system. | 11259 The following signals shall be supported on all implementations (default actions are explained 11260 below the table): 11261 _____________________________________________________________________________________ 11262 _ Signal Default Action Description ____________________________________________________________________________________ 11263 SIGABRT A Process abort signal. 11264 SIGALRM T Alarm clock. 11265 SIGBUS A Access to an undefined portion of a memory object. 11266 SIGCHLD I Child process terminated or stopped. 11267 SIGCONT C Continue executing, if stopped. 11268 SIGFPE A Erroneous arithmetic operation. 11269 SIGHUP T Hangup. 11270 SIGILL A Illegal instruction. 11271 SIGINT T Terminal interrupt signal. 11272 SIGKILL T Kill (cannot be caught or ignored). 11273 SIGPIPE T Write on a pipe with no one to read it. 11274 SIGQUIT A Terminal quit signal. 11275 SIGSEGV A Invalid memory reference. 11276 SIGSTOP S Stop executing (cannot be caught or ignored). 11277 SIGTERM T Termination signal. 11278 SIGTSTP S Terminal stop signal. 11279 SIGTTIN S Background process attempting read. 11280 SIGTTOU S Background process attempting write. 11281 SIGUSR1 T User-defined signal 1. 11282 SIGUSR2 T User-defined signal 2. 11283 XSI SIGPOLL T Pollable event. 11284 SIGPROF T Profiling timer expired. 11285 SIGSYS A Bad system call. 11286 SIGTRAP A Trace/breakpoint trap. 11287 SIGURG I High bandwidth data is available at a socket. 11288 XSI SIGVTALRM T Virtual timer expired. 11289 SIGXCPU A CPU time limit exceeded. 11290 _ SIGXFSZ A File size limit exceeded. ____________________________________________________________________________________ 11291 The default actions are as follows: 11292 T Abnormal termination of the process. The process is terminated with all the consequences | 11293 of _exit( ) except that the status made available to wait( ) and waitpid( ) indicates abnormal 11294 termination by the specified signal. | 11295 A Abnormal termination of the process. | 11296 XSI Additionally, implementation-defined abnormal termination actions, such as creation of a | 11297 core file, may occur. | Base Definitions, Issue 6 339 Headers 11298 I Ignore the signal. | 11299 S Stop the process. | 11300 C Continue the process, if it is stopped; otherwise, ignore the signal. | 11301 The header shall provide a declaration of struct sigaction, including at least the following 11302 members: 11303 void (*sa_handler)(int) What to do on receipt of signal. 11304 sigset_t sa_mask Set of signals to be blocked during execution 11305 of the signal handling function. 11306 int sa_flags Special flags. 11307 void (*)(int, siginfo_t *, void *) sa_sigaction 11308 Pointer to signal handler function or one 11309 of the macros SIG_IGN or SIG_DFL. 11310 XSI The storage occupied by sa_handler and sa_sigaction may overlap, and a portable program must 11311 not use both simultaneously. 11312 The following shall be declared as constants: 11313 SA_NOCLDSTOP Do not generate SIGCHLD when children stop. 11314 SIG_BLOCK The resulting set is the union of the current set and the signal set pointed 11315 to by the argument set. 11316 SIG_UNBLOCK The resulting set is the intersection of the current set and the complement 11317 of the signal set pointed to by the argument set. 11318 SIG_SETMASK The resulting set is the signal set pointed to by the argument set. 11319 XSI SA_ONSTACK Causes signal delivery to occur on an alternate stack. 11320 XSI SA_RESETHAND Causes signal dispositions to be set to SIG_DFL on entry to signal 11321 handlers. 11322 XSI SA_RESTART Causes certain functions to become restartable. 11323 XSI SA_SIGINFO Causes extra information to be passed to signal handlers at the time of 11324 receipt of a signal. 11325 XSI SA_NOCLDWAIT Causes implementations not to create zombie processes on child death. 11326 XSI SA_NODEFER Causes signal not to be automatically blocked on entry to signal handler. 11327 XSI SS_ONSTACK Process is executing on an alternate signal stack. 11328 XSI SS_DISABLE Alternate signal stack is disabled. 11329 XSI MINSIGSTKSZ Minimum stack size for a signal handler. 11330 XSI SIGSTKSZ Default size in bytes for the alternate signal stack. 11331 XSI The ucontext_t structure shall be defined through typedef as described in . | 11332 The mcontext_t type shall be defined through typedef as described in . | 11333 The header shall define the stack_t type as a structure that includes at least the | 11334 following members: 11335 void *ss_sp Stack base or pointer. 11336 size_t ss_size Stack size. 11337 int ss_flags Flags. 340 Technical Standard (2000) (Draft July 28, 2000) Headers 11338 The header shall define the sigstack structure that includes at least the following 11339 members: 11340 int ss_onstack Non-zero when signal stack is in use. 11341 void *ss_sp Signal stack pointer. 11342 11343 The header shall define the siginfo_t type as a structure that includes at least the 11344 following members: 11345 int si_signo Signal number. 11346 XSI int si_errno If non-zero, an errno value associated with 11347 this signal, as defined in . 11348 int si_code Signal code. 11349 XSI pid_t si_pid Sending process ID. 11350 uid_t si_uid Real user ID of sending process. 11351 void *si_addr Address of faulting instruction. 11352 int si_status Exit value or signal. 11353 long si_band Band event for SIGPOLL. 11354 RTS union sigval si_value Signal value. 11355 11356 The macros specified in the Code column of the following table are defined for use as values of 11357 XSI si_code that are signal-specific ornon-signal-specific reasons why the signal was generated. Base Definitions, Issue 6 341 Headers 11358 ______________________________________________________________________________________ 11359 _ Signal Code Reason _____________________________________________________________________________________ 11360 XSI SIGILL ILL_ILLOPC Illegal opcode. 11361 ILL_ILLOPN Illegal operand. 11362 ILL_ILLADR Illegal addressing mode. 11363 ILL_ILLTRP Illegal trap. 11364 ILL_PRVOPC Privileged opcode. 11365 ILL_PRVREG Privileged register. 11366 ILL_COPROC Coprocessor error. 11367 _ ILL_BADSTK Internal stack error. _____________________________________________________________________________________ 11368 SIGFPE FPE_INTDIV Integer divide by zero. 11369 FPE_INTOVF Integer overflow. 11370 FPE_FLTDIV Floating point divide by zero. 11371 FPE_FLTOVF Floating point overflow. 11372 FPE_FLTUND Floating point underflow. 11373 FPE_FLTRES Floating point inexact result. 11374 FPE_FLTINV Invalid floating point operation. 11375 _ FPE_FLTSUB Subscript out of range. _____________________________________________________________________________________ 11376 SIGSEGV SEGV_MAPERR Address not mapped to object. 11377 _ SEGV_ACCERR Invalid permissions for mapped object. _____________________________________________________________________________________ 11378 SIGBUS BUS_ADRALN Invalid address alignment. 11379 BUS_ADRERR Non-existent physical address. 11380 _ BUS_OBJERR Object specific hardware error. _____________________________________________________________________________________ 11381 SIGTRAP TRAP_BRKPT Process breakpoint. 11382 _ TRAP_TRACE Process trace trap. _____________________________________________________________________________________ 11383 SIGCHLD CLD_EXITED Child has exited. 11384 CLD_KILLED Child has terminated abnormally and did not create a core file. 11385 CLD_DUMPED Child has terminated abnormally and created a core file. 11386 CLD_TRAPPED Traced child has trapped. 11387 CLD_STOPPED Child has stopped. 11388 _ CLD_CONTINUED Stopped child has continued. _____________________________________________________________________________________ 11389 SIGPOLL POLL_IN Data input available. 11390 POLL_OUT Output buffers available. 11391 POLL_MSG Input message available. 11392 POLL_ERR I/O error. 11393 POLL_PRI High priority input available. 11394 _ POLL_HUP Device disconnected. _____________________________________________________________________________________ 11395 Any SI_USER Signal sent by kill( ). 11396 SI_QUEUE Signal sent by the sigqueue( ). 11397 SI_TIMER Signal generated by expiration of a timer set by timer_settime( ). 11398 SI_ASYNCIO Signal generated by completion of an asynchronous I/O 11399 request. 11400 SI_MESGQ Signal generated by arrival of a message on an empty message 11401 _ queue. _____________________________________________________________________________________ 11402 XSI Implementations may support additional si_code values not included in this list, may generate 11403 values included in this list under circumstances other than those described in this list, and may 11404 contain extensions or limitations that prevent some values from being generated. 11405 Implementations do not generate a different value from the ones described in this list for 11406 circumstances described in this list. 342 Technical Standard (2000) (Draft July 28, 2000) Headers 11407 In addition, the following signal-specific information shall be available: 11408 _____________________________________________________________________________________ 11409 _ Signal Member Value ____________________________________________________________________________________ 11410 SIGILL void * si_addr Address of faulting instruction. 11411 _ SIGFPE ____________________________________________________________________________________ 11412 SIGSEGV void * si_addr Address of faulting memory reference. 11413 _ SIGBUS ____________________________________________________________________________________ 11414 SIGCHLD pid_t si_pid Child process ID. 11415 int si_status Exit value or signal. 11416 _ uid_t si_uid Real user ID of the process that sent the signal. ____________________________________________________________________________________ 11417 _ SIGPOLL long si_band Band event for POLL_IN, POLL_OUT, or POLL_MSG. ____________________________________________________________________________________ 11418 For some implementations, the value of si_addr may be inaccurate. 11419 The following shall be declared as functions and may also be defined as macros: 11420 XSI void (*bsd_signal(int, void (*)(int)))(int); 11421 int kill(pid_t, int); 11422 XSI int killpg(pid_t, int); 11423 int pthread_kill(pthread_t, int); 11424 int pthread_sigmask(int, const sigset_t *, sigset_t *); 11425 int raise(int); 11426 int sigaction(int, const struct sigaction *restrict, 11427 struct sigaction *restrict); 11428 int sigaddset(sigset_t *, int); 11429 XSI int sigaltstack(const stack_t *restrict, stack_t *restrict); 11430 int sigdelset(sigset_t *, int); 11431 int sigemptyset(sigset_t *); 11432 int sigfillset(sigset_t *); 11433 XSI int sighold(int); 11434 int sigignore(int); 11435 int siginterrupt(int, int); 11436 int sigismember(const sigset_t *, int); 11437 void (*signal(int, void (*)(int)))(int); 11438 XSI int sigpause(int); 11439 int sigpending(sigset_t *); 11440 int sigprocmask(int, const sigset_t *restrict, sigset_t *restrict); 11441 RTS int sigqueue(pid_t, int, const union sigval); 11442 XSI int sigrelse(int); 11443 void (*sigset(int, void (*)(int)))(int); 11444 int sigstack(struct sigstack *, struct sigstack *); (LEGACY) 11445 int sigsuspend(const sigset_t *); 11446 RTS int sigtimedwait(const sigset_t *restrict, siginfo_t *restrict, 11447 const struct timespec *restrict); 11448 int sigwait(const sigset_t *restrict, int *restrict); 11449 RTS int sigwaitinfo(const sigset_t *restrict, siginfo_t *restrict); 11450 Base Definitions, Issue 6 343 Headers 11451 APPLICATION USAGE 11452 None. 11453 RATIONALE 11454 None. 11455 FUTURE DIRECTIONS 11456 None. 11457 SEE ALSO 11458 , , , , the System Interfaces volume of 11459 IEEE Std. 1003.1-200x, alarm( ), bsd_signal( ), ioctl( ), kill( ), killpg( ), raise( ), sigaction( ), sigaddset( ), 11460 sigaltstack( ), sigdelset( ), sigemptyset( ), sigfillset( ), siginterrupt( ), sigismember( ), signal( ), 11461 sigpending( ), sigprocmask( ), sigqueue( ), sigsuspend( ), sigwaitinfo ( ), wait( ), waitid( ) 11462 CHANGE HISTORY 11463 First released in Issue 1. 11464 Issue 4 11465 A reference to is added for the definition of pid_t. This is marked as an extension. 11466 In the list of signals starting with SIGCHLD, the statement ``but a system not supporting the job 11467 control option is not obliged to support the functionality of these signals'' is removed. This is 11468 because job control is defined as mandatory on Issue 4 conforming implementations. 11469 Reference to implementation-defined abnormal termination routines, such as creation of a core | 11470 file, in item ii in the defaults action list is marked as an extension. 11471 The following changes are incorporated for alignment with the ISO POSIX-1 standard: 11472 * The function declarations in this header are expanded to full ISO C standard prototypes. 11473 * The DESCRIPTION is changed as follows: 11474 - To define the type sig_atomic_t. 11475 - To define the syntax of signal names and functions. 11476 - To combine the two tables of constants. 11477 - SIGFPE is no longer limited to floating-point exceptions, but covers all erroneous 11478 arithmetic operations. 11479 The following change is incorporated for alignment with the ISO C standard: 11480 * The raise( ) function is added to the list of functions declared in this header. 11481 Issue 4, Version 2 11482 The following changes are incorporated for X/OPEN UNIX conformance: 11483 * The SIGTRAP, SIGBUS, SIGSYS, SIGPOLL, SIGPROF, SIGXCPU, SIGXFSZ, SIGURG, and 11484 SIGVTALRM signals are added to the list of signals that are supported on all conforming 11485 implementations. 11486 * The sa_sigaction member is added to the sigaction structure, and a note is added that the 11487 storage used by sa_handler and sa_sigaction may overlap. 11488 * The SA_ONSTACK, SA_RESETHAND, SA_RESTART, SA_SIGINFO, SA_NOCLDWAIT, 11489 SS_ONSTACK, SS_DISABLE, MINSIGSTKSZ, and SIGSTKSZ constants are defined. The 11490 stack_t, sigstack, and siginfo structures are defined. 11491 * Definitions are given for the ucontext_t, stack_t, sigstack, and siginfo_t types. 344 Technical Standard (2000) (Draft July 28, 2000) Headers 11492 * A table is provided listing macros that are defined as signal-specific reasons why a signal 11493 was generated. Signal-specific additional information is specified. 11494 * The bsd_signal( ), killpg ( ), _longjmp( ), _setjmp( ), sigaltstack ( ), sighold ( ), sigignore( ), 11495 siginterrupt( ), sigpause( ), sigrelse( ), sigset( ), and sigstack( ) functions are added to the list of 11496 functions declared in this header. 11497 Issue 5 11498 The DESCRIPTION is updated for alignment with POSIX Realtime Extension and the POSIX 11499 Threads Extension. 11500 The default action for SIGURG is changed for i to iii. The function prototype for sigmask( ) is 11501 removed. 11502 Issue 6 11503 The Open Group corrigenda item U035/2 has been applied. In the DESCRIPTION, the wording 11504 for abnormal termination is clarified. 11505 The Open Group corrigenda item U028/8 has been applied, correcting the prototype for the 11506 sigset( ) function. 11507 The Open Group corrigenda item U026/3 has been applied, correcting the type of the 11508 sigev_notify_function function member of the sigevent structure. 11509 The following new requirements on POSIX implementations derive from alignment with the 11510 Single UNIX Specification: 11511 * The SIGCHLD, SIGCONT, SIGSTOP, SIGTSTP, SIGTTIN, and SIGTTOU signals are now 11512 mandated. This is also a FIPS requirement. 11513 * The pid_t definition is mandated. 11514 The RT markings are now changed to RTS to denote that the semantics are part of the Realtime 11515 Signals Extension option. 11516 The restrict keyword is added to the prototypes for sigaction( ), sigaltstack( ), sigprocmask( ), | 11517 sigtimedwait( ), sigwait( ), and sigwaitinfo ( ). | Base Definitions, Issue 6 345 Headers 11518 NAME 11519 spawn.h - spawn (REALTIME) 11520 SYNOPSIS 11521 SPN #include 11522 11523 DESCRIPTION 11524 The header shall define the posix_spawnattr_t and posix_spawn_file_actions_t 11525 types used in performing spawn operations. 11526 The header shall define the flags that may be set in a posix_spawnattr_t object using 11527 the posix_spawnattr_setflags( ) function: 11528 POSIX_SPAWN_RESETIDS 11529 POSIX_SPAWN_SETPGROUP 11530 PS POSIX_SPAWN_SETSCHEDPARAM 11531 POSIX_SPAWN_SETSCHEDULER 11532 POSIX_SPAWN_SETSIGDEF 11533 POSIX_SPAWN_SETSIGMASK 11534 The following shall be declared as functions and may also be declared as macros. Function 11535 prototypes shall be provided for use with an ISO C standard compiler. 11536 int posix_spawn(pid_t *restrict, const char *restrict, 11537 const posix_spawn_file_actions_t *, 11538 const posix_spawnattr_t *restrict, char *const [restrict], 11539 char *const [restrict]); 11540 int posix_spawn_file_actions_addclose(posix_spawn_file_actions_t *, 11541 int); 11542 int posix_spawn_file_actions_adddup2(posix_spawn_file_actions_t *, 11543 int, int); 11544 int posix_spawn_file_actions_addopen(posix_spawn_file_actions_t *restrict, 11545 int, const char *restrict, int, mode_t); 11546 int posix_spawn_file_actions_destroy(posix_spawn_file_actions_t *); 11547 int posix_spawn_file_actions_init(posix_spawn_file_actions_t *); 11548 int posix_spawnattr_destroy(posix_spawnattr_t *); 11549 int posix_spawnattr_getsigdefault(const posix_spawnattr_t *restrict, 11550 sigset_t *restrict); 11551 int posix_spawnattr_getflags(const posix_spawnattr_t *restrict, 11552 short *restrict); 11553 int posix_spawnattr_getpgroup(const posix_spawnattr_t *restrict, 11554 pid_t *restrict); 11555 PS int posix_spawnattr_getschedparam(const posix_spawnattr_t *restrict, 11556 struct sched_param *restrict); 11557 int posix_spawnattr_getschedpolicy(const posix_spawnattr_t *restrict, 11558 int *restrict); 11559 int posix_spawnattr_getsigmask(const posix_spawnattr_t *restrict, 11560 sigset_t *restrict); 11561 int posix_spawnattr_init(posix_spawnattr_t *); 11562 int posix_spawnattr_setsigdefault(posix_spawnattr_t *restrict, 11563 const sigset_t *restrict); 11564 int posix_spawnattr_setflags(posix_spawnattr_t *, short); 11565 int posix_spawnattr_setpgroup(posix_spawnattr_t *, pid_t); 11566 PS 346 Technical Standard (2000) (Draft July 28, 2000) Headers 11567 int posix_spawnattr_setschedparam(posix_spawnattr_t *restrict, 11568 const struct sched_param *restrict); 11569 int posix_spawnattr_setschedpolicy(posix_spawnattr_t *, int); 11570 int posix_spawnattr_setsigmask(posix_spawnattr_t *restrict, 11571 const sigset_t *restrict); 11572 const posix_spawnattr_t *, char *const [], char *const []); 11573 int posix_spawnp(pid_t *restrict, const char *restrict, 11574 const posix_spawn_file_actions_t *, 11575 const posix_spawnattr_t *restrict, 11576 char *const [restrict], char *const [restrict]); 11577 Inclusion of the header may make visible symbols defined in the , | 11578 , and headers. | 11579 APPLICATION USAGE 11580 None. 11581 RATIONALE 11582 None. 11583 FUTURE DIRECTIONS 11584 None. 11585 SEE ALSO 11586 , , , , the System Interfaces volume of | 11587 IEEE Std. 1003.1-200x, posix_spawnattr_destroy( ), posix_spawnattr_getsigdefault( ), | 11588 posix_spawnattr_getflags( ), posix_spawnattr_getpgroup( ), posix_spawnattr_getschedparam( ), 11589 posix_spawnattr_getschedpolicy( ), posix_spawnattr_getsigmask( ), posix_spawnattr_init( ), | 11590 posix_spawnattr_setsigdefault( ), posix_spawnattr_setflags( ), posix_spawnattr_setpgroup( ), | 11591 posix_spawnattr_setschedparam( ), posix_spawnattr_setschedpolicy( ), posix_spawnattr_setsigmask( ), 11592 posix_spawn( ), posix_spawn_file_actions_addclose( ), posix_spawn_file_actions_adddup2( ), 11593 posix_spawn_file_actions_addopen( ), posix_spawn_file_actions_destroy( ), 11594 posix_spawn_file_actions_init( ), posix_spawnp( ) 11595 CHANGE HISTORY 11596 First released in Issue 6. Included for alignment with IEEE Std. 1003.1d-1999. | 11597 The restrict keyword is added to the prototypes for posix_spawn( ), | 11598 posix_spawn_file_actions_addopen( ), posix_spawnattr_getsigdefault( ), posix_spawnattr_getflags( ), | 11599 posix_spawnattr_getpgroup( ), posix_spawnattr_getschedparam( ), posix_spawnattr_getschedpolicy( ), | 11600 posix_spawnattr_getsigmask( ), posix_spawnattr_setsigdefault( ), posix_spawnattr_setschedparam( ), | 11601 posix_spawnattr_setsigmask( ), and posix_spawnp( ). | Base Definitions, Issue 6 347 Headers 11602 NAME 11603 stdarg.h - handle variable argument list 11604 SYNOPSIS 11605 #include 11606 void va_start(va_list ap, argN); 11607 void va_copy(va_list dest, va_list src); | 11608 type va_arg(va_list ap, type); | 11609 void va_end(va_list ap); 11610 DESCRIPTION 11611 CX The functionality described on this reference page extends the ISO C standard. Applications 11612 shall define the appropriate feature test macro (see the System Interfaces volume of 11613 IEEE Std. 1003.1-200x, Section 2.2, The Compilation Environment) to enable the visibility of 11614 symbols in this header. 11615 The header contains a set of macros which allows portable functions that accept 11616 variable argument lists to be written. Functions that have variable argument lists (such as 11617 printf( )) but do not use these macros, are inherently non-portable, as different systems use 11618 different argument-passing conventions. 11619 The type va_list is defined for variables used to traverse the list. 11620 The va_start( ) macro is invoked to initialize ap to the beginning of the list before any calls to 11621 va_arg( ). 11622 The va_copy( ) macro initializes as a copy of src, as if the va_start( ) macro had been applied to | 11623 dest followed by the same sequence of uses of the va_arg( ) macro as had previously been used to | 11624 reach the present state of src. Neither the va_copy( ) nor va_start( ) macro shall be invoked to | 11625 reinitialize dest without an intervening invocation of the va_end( ) macro for the same dest. | 11626 The object ap may be passed as an argument to another function; if that function invokes the | 11627 va_arg( ) macro with parameter ap, the value of ap in the calling function is indeterminate and 11628 must be passed to the va_end( ) macro prior to any further reference to ap. The parameter argN is 11629 the identifier of the rightmost parameter in the variable parameter list in the function definition 11630 (the one just before the . . .). If the parameter argN is declared with the register storage class, with 11631 a function type or array type, or with a type that is not compatible with the type that results after 11632 application of the default argument promotions, the behavior is undefined. 11633 The va_arg( ) macro returns the next argument in the list pointed to by ap. Each invocation of 11634 va_arg( ) modifies ap so that the values of successive arguments are returned in turn. The type 11635 parameter is the type the argument is expected to be. This is the type name specified such that 11636 the type of a pointer to an object that has the specified type can be obtained simply by suffixing 11637 a '*' to type. Different types can be mixed, but it is up to the routine to know what type of 11638 argument is expected. 11639 The va_end( ) macro is used to clean up; it invalidates ap for use (unless va_start( ) or va_copy( ) is | 11640 invoked again). 11641 Each invocation of the va_start( ) and va_copy( ) macros shall be matched by a corresponding | 11642 invocation of the va_end( ) macro in the same function. | 11643 Multiple traversals, each bracketed by va_start( ) . . . va_end( ), are possible. | 348 Technical Standard (2000) (Draft July 28, 2000) Headers 11644 EXAMPLES 11645 This example is a possible implementation of execl( ): 11646 #include 11647 #define MAXARGS 31 11648 /* 11649 * execl is called by 11650 * execl(file, arg1, arg2, ..., (char *)(0)); 11651 */ 11652 int execl(const char *file, const char *args, ...) 11653 { 11654 va_list ap; 11655 char *array[MAXARGS]; 11656 int argno = 0; 11657 va_start(ap, args); 11658 while (args != 0) { 11659 array[argno++] = args; 11660 args = va_arg(ap, const char *); 11661 } 11662 va_end(ap); 11663 return execv(file, array); 11664 } 11665 APPLICATION USAGE 11666 It is up to the calling routine to communicate to the called routine how many arguments there 11667 are, since it is not always possible for the called routine to determine this in any other way. For 11668 example, execl( ) is passed a null pointer to signal the end of the list. The printf( ) function can tell 11669 how many arguments are there by the format argument. 11670 RATIONALE 11671 None. 11672 FUTURE DIRECTIONS 11673 None. 11674 SEE ALSO 11675 The System Interfaces volume of IEEE Std. 1003.1-200x, exec( ), printf( ) 11676 CHANGE HISTORY | 11677 First released in Issue 4. Derived from the ANSI C standard. | Base Definitions, Issue 6 349 Headers 11678 NAME | 11679 stdbool.h - boolean type and values | 11680 SYNOPSIS | 11681 #include | 11682 DESCRIPTION | 11683 CX The functionality described on this reference page extends the ISO C standard. Applications | 11684 shall define the appropriate feature test macro (see the System Interfaces volume of | 11685 IEEE Std. 1003.1-200x, Section 2.2, The Compilation Environment) to enable the visibility of | 11686 symbols in this header. | 11687 The header shall define the following macros: | 11688 bool Expands to _Bool. | 11689 true Expands to the integer constant 1. | 11690 false Expands to the integer constant 0. | 11691 _ _bool_true_false_are_defined | 11692 Expands to the integer constant 1. | 11693 An application may undefine and then possibly redefine the macros bool, true, and false. | 11694 APPLICATION USAGE | 11695 None. | 11696 RATIONALE | 11697 None. | 11698 FUTURE DIRECTIONS | 11699 The ability to undefine and redefine the macros bool, true, and false is an obsolescent feature and | 11700 may be withdrawn in the future. | 11701 SEE ALSO | 11702 None. | 11703 CHANGE HISTORY | 11704 First released in Issue 6. Included for alignment with the ISO/IEC 9899: 1999 standard. | 350 Technical Standard (2000) (Draft July 28, 2000) Headers 11705 NAME 11706 stddef.h - standard type definitions 11707 SYNOPSIS 11708 #include 11709 DESCRIPTION 11710 CX The functionality described on this reference page extends the ISO C standard. Applications 11711 shall define the appropriate feature test macro (see the System Interfaces volume of 11712 IEEE Std. 1003.1-200x, Section 2.2, The Compilation Environment) to enable the visibility of 11713 symbols in this header. 11714 The header shall define the following: 11715 NULL Null pointer constant. 11716 offsetof(type, member-designator) 11717 Integral constant expression of type size_t, the value of which is the offset in bytes 11718 to the structure member (member-designator), from the beginning of its structure 11719 (type). 11720 The header shall define through typedef: 11721 ptrdiff_t Signed integer type of the result of subtracting two pointers. | 11722 wchar_t Integer type whose range of values can represent distinct wide-character codes for | 11723 all members of the largest character set specified among the locales supported by 11724 the compilation environment: the null character has the code value 0 and each 11725 member of the Portable Character Set has a code value equal to its value when 11726 used as the lone character in an integer character constant. 11727 size_t Unsigned integer type of the result of the sizeof operator. | 11728 APPLICATION USAGE 11729 None. 11730 RATIONALE 11731 None. 11732 FUTURE DIRECTIONS 11733 None. 11734 SEE ALSO 11735 , 11736 CHANGE HISTORY | 11737 First released in Issue 4. Derived from the ANSI C standard. | Base Definitions, Issue 6 351 Headers 11738 NAME | 11739 stdint.h - integer types | 11740 SYNOPSIS | 11741 #include | 11742 DESCRIPTION | 11743 CX The functionality described on this reference page extends the ISO C standard. Applications | 11744 shall define the appropriate feature test macro (see the System Interfaces volume of | 11745 IEEE Std. 1003.1-200x, Section 2.2, The Compilation Environment) to enable the visibility of | 11746 symbols in this header. | 11747 The header declares sets of integer types having specified widths, and defines | 11748 corresponding sets of macros. It also defines macros that specify limits of integer types | 11749 corresponding to types defined in other standard headers. | 11750 Types are defined in the following categories: | 11751 * Integer types having certain exact widths | 11752 * Integer types having at least certain specified widths | 11753 * Fastest integer types having at least certain specified widths | 11754 * Integer types wide enough to hold pointers to objects | 11755 * Integer types having greatest width | 11756 (Some of these types may denote the same type.) | 11757 Corresponding macros specify limits of the declared types and construct suitable constants. | 11758 For each type described herein that the implementation provides, the header shall | 11759 declare that typedef name and define the associated macros. Conversely, for each type described | 11760 herein that the implementation does not provide, the header shall not declare that | 11761 typedef name, nor shall it define the associated macros. An implementation shall provide those | 11762 types described as required, but need not provide any of the others (described as optional). | 11763 Integer Types | 11764 When typedef names differing only in the absence or presence of the initial u are defined, they | 11765 shall denote corresponding signed and unsigned types as described in the ISO/IEC 9899: 1999 | 11766 standard, Section 6.2.5; an implementation providing one of these corresponding types shall also | 11767 provide the other. | 11768 In the following descriptions, the symbol N represents an unsigned decimal integer with no | 11769 leading zeros (for example, 8 or 24, but not 04 or 048). | 11770 * Exact-width integer types | 11771 The typedef name intN_t designates a signed integer type with width N, no padding bits, | 11772 and a two's-complement representation. Thus, int8_t denotes a signed integer type with a | 11773 width of exactly 8 bits. | 11774 The typedef name uintN_t designates an unsigned integer type with width N. Thus, | 11775 uint24_t denotes an unsigned integer type with a width of exactly 24 bits. | 11776 These types are optional. However, if an implementation provides integer types with widths | 11777 of 8, 16, 32, or 64 bits, it shall define the corresponding typedef names. | 11778 * Minimum-width integer types | 352 Technical Standard (2000) (Draft July 28, 2000) Headers 11779 The typedef name int_leastN_t designates a signed integer type with a width of at least N, | 11780 such that no signed integer type with lesser size has at least the specified width. Thus, | 11781 int_least32_t denotes a signed integer type with a width of at least 32 bits. | 11782 The typedef name uint_leastN_t designates an unsigned integer type with a width of at least | 11783 N, such that no unsigned integer type with lesser size has at least the specified width. Thus, | 11784 uint_least16_t denotes an unsigned integer type with a width of at least 16 bits. | 11785 The following types are required: | 11786 int_least8_t | 11787 int_least16_t | 11788 int_least32_t | 11789 int_least64_t | 11790 uint_least8_t | 11791 uint_least16_t | 11792 uint_least32_t | 11793 uint_least64_t | 11794 All other types of this form are optional. | 11795 * Fastest minimum-width integer types | 11796 Each of the following types designates an integer type that is usually fastest to operate with | 11797 among all integer types that have at least the specified width. | 11798 The designated type is not guaranteed to be fastest for all purposes; if the implementation | 11799 has no clear grounds for choosing one type over another, it will simply pick some integer | 11800 type satisfying the signedness and width requirements. | 11801 The typedef name int_fastN_t designates the fastest signed integer type with a width of at | 11802 least N. The typedef name uint_fastN_t designates the fastest unsigned integer type with a | 11803 width of at least N. | 11804 The following types are required: | 11805 int_fast8_t | 11806 int_fast16_t | 11807 int_fast32_t | 11808 int_fast64_t | 11809 uint_fast8_t | 11810 uint_fast16_t | 11811 uint_fast32_t | 11812 uint_fast64_t | 11813 All other types of this form are optional. | 11814 * Integer types capable of holding object pointers | 11815 The following type designates a signed integer type with the property that any valid pointer | 11816 to void can be converted to this type, then converted back to a pointer to void, and the result | 11817 will compare equal to the original pointer: | 11818 intptr_t | 11819 The following type designates an unsigned integer type with the property that any valid | 11820 pointer to void can be converted to this type, then converted back to a pointer to void, and | 11821 the result will compare equal to the original pointer: | Base Definitions, Issue 6 353 Headers 11822 uintptr_t | 11823 These types are optional. | 11824 * Greatest-width integer types | 11825 The following type designates a signed integer type capable of representing any value of any | 11826 signed integer type: | 11827 intmax_t | 11828 The following type designates an unsigned integer type capable of representing any value of | 11829 any unsigned integer type: | 11830 uintmax_t | 11831 These types are required. | 11832 Limits of Specified-Width Integer Types | 11833 The following object-like macros specify the minimum and maximum limits of the types | 11834 declared in the header. Each macro name corresponds to a similar type name in | 11835 Integer Types (on page 352). | 11836 Each instance of any defined macro shall be replaced by a constant expression suitable for use in | 11837 #if preprocessing directives, and this expression shall have the same type as would an | 11838 expression that is an object of the corresponding type converted according to the integer | 11839 promotions. Its implementation-defined value shall be equal to or greater in magnitude | 11840 (absolute value) than the corresponding value given below, with the same sign, except where | 11841 stated to be exactly the given value. | 11842 * Limits of exact-width integer types | 11843 - Minimum values of exact-width signed integer types: | 11844 {INTN_MIN} Exactly -(2N-1) | 11845 - Maximum values of exact-width signed integer types: | 11846 {INTN_MAX} Exactly 2N-1 -1 | 11847 - Maximum values of exact-width unsigned integer types: | 11848 {UINTN_MAX} Exactly 2N -1 | 11849 * Limits of minimum-width integer types | 11850 - Minimum values of minimum-width signed integer types: | 11851 {INT_LEASTN_MIN} -(2N-1 -1) | 11852 - Maximum values of minimum-width signed integer types: | 11853 {INT_LEASTN_MAX} 2N -1 | 11854 - Maximum values of minimum-width unsigned integer types: | 11855 {UINT_LEASTN_MAX} 2N -1 | 11856 * Limits of fastest minimum-width integer types | 11857 - Minimum values of fastest minimum-width signed integer types: | 11858 {INT_FASTN_MIN} -(2N-1 -1) | 354 Technical Standard (2000) (Draft July 28, 2000) Headers 11859 - Maximum values of fastest minimum-width signed integer types: | 11860 {INT_FASTN_MAX} 2N-1 -1 | 11861 - Maximum values of fastest minimum-width unsigned integer types: | 11862 {UINT_FASTN_MAX} 2N -1 | 11863 * Limits of integer types capable of holding object pointers | 11864 - Minimum value of pointer-holding signed integer type: | 11865 {INTPTR_MIN} -(215 -1) | 11866 - Maximum value of pointer-holding signed integer type: | 11867 {INTPTR_MAX} 215 -1 | 11868 - Maximum value of pointer-holding unsigned integer type: | 11869 {UINTPTR_MAX} 216 -1 | 11870 * Limits of greatest-width integer types | 11871 - Minimum value of greatest-width signed integer type: | 11872 {INTMAX_MIN} -(263 -1) | 11873 - Maximum value of greatest-width signed integer type: | 11874 {INTMAX_MAX} 263 -1 | 11875 - Maximum value of greatest-width unsigned integer type: | 11876 {UINTMAX_MAX} 264 -1 | 11877 Limits of Other Integer Types | 11878 The following object-like macros specify the minimum and maximum limits of integer types | 11879 corresponding to types defined in other standard headers. | 11880 Each instance of these macros shall be replaced by a constant expression suitable for use in #if | 11881 preprocessing directives, and this expression shall have the same type as would an expression | 11882 that is an object of the corresponding type converted according to the integer promotions. Its | 11883 implementation-defined value shall be equal to or greater in magnitude (absolute value) than | 11884 the corresponding value given below, with the same sign. | 11885 * Limits of ptrdiff_t: | 11886 {PTRDIFF_MIN} -65535 | 11887 {PTRDIFF_MAX} +65535 | 11888 * Limits of sig_atomic_t: | 11889 {SIG_ATOMIC_MIN} See below. | 11890 {SIG_ATOMIC_MAX} See below. | 11891 * Limit of size_t: | 11892 {SIZE_MAX} 65535 | 11893 * Limits of wchar_t: | 11894 {WCHAR_MIN} See below. | Base Definitions, Issue 6 355 Headers 11895 {WCHAR_MAX} See below. | 11896 * Limits of wint_t: | 11897 {WINT_MIN} See below. | 11898 [WINT_MAX} See below. | 11899 If sig_atomic_t (see the header) is defined as a signed integer type, the value of | 11900 {SIG_ATOMIC_MIN} shall be no greater than -127 and the value of {SIG_ATOMIC_MAX} shall | 11901 be no less than 127; otherwise, sig_atomic_t is defined as an unsigned integer type, and the | 11902 value of {SIG_ATOMIC_MIN} shall be 0 and the value of {SIG_ATOMIC_MAX} shall be no less | 11903 than 255. | 11904 If wchar_t (see the header) is defined as a signed integer type, the value of | 11905 {WCHAR_MIN} shall be no greater than -127 and the value of {WCHAR_MAX} shall be no less | 11906 than 127; otherwise, wchar_t is defined as an unsigned integer type, and the value of | 11907 {WCHAR_MIN} shall be 0 and the value of {WCHAR_MAX} shall be no less than 255. | 11908 If wint_t (see the header) is defined as a signed integer type, the value of | 11909 {WINT_MIN} shall be no greater than -32767 and the value of {WINT_MAX} shall be no less | 11910 than 32767; otherwise, wint_t is defined as an unsigned integer type, and the value of | 11911 {WINT_MIN} shall be 0 and the value of {WINT_MAX} shall be no less than 65535. | 11912 Macros for Integer Constants | 11913 The following function-like macros expand to integer constants suitable for initializing objects | 11914 that have integer types corresponding to types defined in the header. Each macro | 11915 name corresponds to a similar type name listed under Minimum-width integer types and Greatest- | 11916 width integer types. | 11917 The argument in any instance of these macros shall be a decimal, octal, or hexadecimal constant | 11918 with a value that does not exceed the limits for the corresponding type. | 11919 * Macros for minimum-width integer constants | 11920 Each of the following macros expands to an integer constant having the value specified by its | 11921 argument and a type with at least the specified width. | 11922 The macro INTN_C(value) shall expand to a signed integer constant with the specified value | 11923 and type int_leastN_t. The macro UINTN_C(value) shall expand to an unsigned integer | 11924 constant with the specified value and type uint_leastN_t. For example, if uint_least64_t is a | 11925 name for the type unsigned long long, then UINT64_C(0x123) might expand to the integer | 11926 constant 0x123ULL. | 11927 * Macros for greatest-width integer constants | 11928 The following macro expands to an integer constant having the value specified by its | 11929 argument and the type intmax_t: | 11930 INTMAX_C(value) | 11931 The following macro expands to an integer constant having the value specified by its | 11932 argument and the type uintmax_t: | 11933 UINTMAX_C(value) | 356 Technical Standard (2000) (Draft July 28, 2000) Headers 11934 APPLICATION USAGE | 11935 None. | 11936 RATIONALE | 11937 The header is a subset of the header more suitable for use in | 11938 freestanding environments, which might not support the formatted I/O functions. In some | 11939 environments, if the formatted conversion support is not wanted, using this header instead of | 11940 the header avoids defining such a large number of macros. | 11941 FUTURE DIRECTIONS | 11942 typedef names beginning with int or uint and ending with _t may be added to the types defined | 11943 in the header. Macro names beginning with INT or UINT and ending with _MAX, | 11944 _MIN, or _C may be added to the macros defined in the header. | 11945 SEE ALSO | 11946 , , , | 11947 CHANGE HISTORY || 11948 First released in Issue 6. Included for alignment with the ISO/IEC 9899: 1999 standard. | Base Definitions, Issue 6 357 Headers 11949 NAME 11950 stdio.h - standard buffered input/output 11951 SYNOPSIS 11952 #include 11953 DESCRIPTION 11954 CX The functionality described on this reference page extends the ISO C standard. Applications 11955 shall define the appropriate feature test macro (see the System Interfaces volume of 11956 IEEE Std. 1003.1-200x, Section 2.2, The Compilation Environment) to enable the visibility of 11957 symbols in this header. 11958 The header shall define the following macro names as positive integral constant 11959 expressions: 11960 {BUFSIZ} Size of buffers. 11961 {FILENAME_MAX} Maximum size in bytes of the longest file name string that the 11962 implementation guarantees can be opened. 11963 {FOPEN_MAX} Number of streams which the implementation guarantees can be open 11964 simultaneously. The value is at least eight. 11965 {_IOFBF} Input/output fully buffered. 11966 {_IOLBF} Input/output line buffered. 11967 {_IONBF} Input/output unbuffered. 11968 {L_ctermid} Maximum size of character array to hold ctermid( ) output. 11969 {L_tmpnam} Maximum size of character array to hold tmpnam( ) output. 11970 {SEEK_CUR} Seek relative to current position. 11971 {SEEK_END} Seek relative to end-of-file. 11972 {SEEK_SET} Seek relative to start-of-file. 11973 {TMP_MAX} Minimum number of unique file names generated by tmpnam( ). 11974 XSI Maximum number of times an application can call tmpnam( ) reliably. 11975 The value of {TMP_MAX} is at least 10,000. 11976 The following macro name shall be defined as a negative integral constant expression: 11977 EOF End-of-file return value. 11978 The following macro name shall be defined as a null pointer constant: 11979 NULL Null pointer. 11980 The following macro name shall be defined as a string constant: 11981 XSI P_tmpdir Default directory prefix for tempnam( ). 11982 The following macro names shall be defined as expressions of type pointer to FILE: 11983 stderr Standard error output stream. 11984 stdin Standard input stream. 11985 stdout Standard output stream. 11986 The following data types shall be defined through typedef: 358 Technical Standard (2000) (Draft July 28, 2000) Headers 11987 FILE A structure containing information about a file. 11988 fpos_t Type containing all information needed to specify uniquely every 11989 position within a file. 11990 XSI va_list As described in . 11991 size_t As described in . 11992 The following shall be declared as functions and may also be defined as macros. Function 11993 prototypes shall be provided for use with an ISO C standard compiler. 11994 void clearerr(FILE *); 11995 char *ctermid(char *); 11996 int fclose(FILE *); 11997 FILE *fdopen(int, const char *); 11998 int feof(FILE *); 11999 int ferror(FILE *); 12000 int fflush(FILE *); 12001 int fgetc(FILE *); 12002 int fgetpos(FILE *restrict, fpos_t *restrict); 12003 char *fgets(char *restrict, int, FILE *restrict); 12004 int fileno(FILE *); 12005 TSF void flockfile(FILE *); 12006 FILE *fopen(const char *restrict, const char *restrict); 12007 int fprintf(FILE *restrict, const char *restrict, ...); 12008 int fputc(int, FILE *); 12009 int fputs(const char *restrict, FILE *restrict); 12010 size_t fread(void *restrict, size_t, size_t, FILE *restrict); 12011 FILE *freopen(const char *restrict, const char *restrict, 12012 FILE *restrict); 12013 int fscanf(FILE *restrict, const char *restrict, ...); 12014 int fseek(FILE *, long, int); 12015 XSI int fseeko(FILE *, off_t, int); 12016 int fsetpos(FILE *, const fpos_t *); 12017 long ftell(FILE *); 12018 XSI off_t ftello(FILE *); 12019 TSF int ftrylockfile(FILE *); 12020 void funlockfile(FILE *); 12021 size_t fwrite(const void *restrict, size_t, size_t, FILE *restrict); 12022 int getc(FILE *); 12023 int getchar(void); 12024 TSF int getc_unlocked(FILE *); 12025 int getchar_unlocked(void); 12026 char *gets(char *); 12027 int pclose(FILE *); 12028 void perror(const char *); 12029 FILE *popen(const char *, const char *); 12030 int printf(const char *restrict, ...); 12031 int putc(int, FILE *); 12032 int putchar(int); 12033 TSF int putc_unlocked(int, FILE *); 12034 int putchar_unlocked(int); 12035 int puts(const char *); 12036 int remove(const char *); Base Definitions, Issue 6 359 Headers 12037 int rename(const char *, const char *); 12038 void rewind(FILE *); 12039 int scanf(const char *restrict, ...); 12040 void setbuf(FILE *restrict, char *restrict); 12041 int setvbuf(FILE *restrict, char *restrict, int, size_t); 12042 XSI int snprintf(char *restrict, size_t, const char *restrict, ...); 12043 int sprintf(char *restrict, const char *restrict, ...); 12044 int sscanf(const char *restrict, const char *restrict, int ...); 12045 XSI char *tempnam(const char *, const char *); 12046 FILE *tmpfile(void); 12047 char *tmpnam(char *); 12048 int ungetc(int, FILE *); 12049 int vfprintf(FILE *restrict, const char *restrict, va_list); 12050 int vfscanf(FILE *restrict, const char *restrict, va_list); 12051 int vprintf(const char *restrict, va_list); 12052 int vscanf(const char *restrict, va_list); 12053 XSI int vsnprintf(char *restrict, size_t, const char *restrict, va_list; 12054 int vsprintf(char *restrict, const char *restrict, va_list); 12055 int vsscanf(const char *restrict, const char *restrict, va_list arg); 12056 XSI Inclusion of the header may also make visible all symbols from . 12057 APPLICATION USAGE 12058 None. 12059 RATIONALE 12060 None. 12061 FUTURE DIRECTIONS 12062 None. 12063 SEE ALSO 12064 , the System Interfaces volume of IEEE Std. 1003.1-200x, clearerr( ), ctermid( ), 12065 fclose( ), fdopen( ), fgetc( ), fgetpos( ), ferror( ), feof( ), fflush( ), fgets( ), fileno( ), flockfile ( ), fopen( ), 12066 fputc( ), fputs( ), fread( ), freopen( ), fseek( ), fsetpos( ), ftell( ), fwrite( ), getc( ), getc_unlocked( ), 12067 getwchar( ), getchar( ), getopt( ), gets( ), pclose( ), perror( ), popen( ), printf( ), putc( ), putchar( ), puts( ), 12068 putwchar( ), remove( ), rename( ), rewind( ), scanf( ), setbuf( ), setvbuf( ), sscanf( ), stdin( ), system( ), 12069 tempnam( ), tmpfile( ), tmpnam( ), ungetc( ), vfscanf( ), vscanf( ), vprintf( ), vsscanf( ) | 12070 CHANGE HISTORY 12071 First released in Issue 1. Derived from Issue 1 of the SVID. | 12072 Issue 4 12073 The constant {L_cuserid} and the external variables optarg, opterr, optind, and optopt are marked | 12074 as extensions and TO BE WITHDRAWN. 12075 The minimum allowable value of {TMP_MAX}, 10,000 on XSI-conformant systems, has been 12076 marked as an extension. 12077 The P_tmpdir constant is moved from the APPLICATION USAGE section to the DESCRIPTION 12078 and marked as an extension. The remainder of the APPLICATION USAGE section is removed. 12079 References to the va_list and size_t types are added to the DESCRIPTION. 12080 Function declarations of the cuserid( ), getopt( ), and tempnam( ) functions and the va_list type are 12081 marked as extensions. 360 Technical Standard (2000) (Draft July 28, 2000) Headers 12082 The cuserid( ) and getopt( ) functions are marked TO BE WITHDRAWN. 12083 A warning is added indicating that inclusion of may also make visible all symbols 12084 from . 12085 The following changes are incorporated for alignment with the ISO C standard: 12086 * The function declarations in this header are expanded to full ISO C standard prototypes. 12087 * The DESCRIPTION is restructured to group lists of macro names according to how they are 12088 defined by an implementation (for example, whether they are integral constant expressions, 12089 pointer constants, or string constants). 12090 * The constant {FILENAME_MAX} is added to the list of integral constant expressions. The 12091 text of {FOPEN_MAX} has also been changed for consistency with the ISO C standard. 12092 * The data type fpos_t is moved from the APPLICATION USAGE section to the 12093 DESCRIPTION. 12094 * The fgetpos( ) and fsetpos( ) functions are added to the list of functions declared in this header. 12095 Issue 5 12096 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 12097 Large File System extensions are added. 12098 The constant {L_cuserid} and the external variables optarg, opterr, optind, and optopt are marked | 12099 as extensions and LEGACY. 12100 The cuserid( ) and getopt( ) functions are marked LEGACY. 12101 Issue 6 12102 The constant {L_cuserid} and the external variables optarg, opterr, optind, and optopt are removed | 12103 as they were previously marked LEGACY. 12104 The cuserid( ) and getopt( ) functions are removed as they were previously marked LEGACY. 12105 Several functions are marked as part of the _POSIX_THREAD_SAFE_FUNCTIONS option. | 12106 This reference page is updated to align with the ISO/IEC 9899: 1999 standard. | Base Definitions, Issue 6 361 Headers 12107 NAME 12108 stdlib.h - standard library definitions 12109 SYNOPSIS 12110 #include 12111 DESCRIPTION 12112 CX The functionality described on this reference page extends the ISO C standard. Applications 12113 shall define the appropriate feature test macro (see the System Interfaces volume of 12114 IEEE Std. 1003.1-200x, Section 2.2, The Compilation Environment) to enable the visibility of 12115 symbols in this header. 12116 The header shall define the following macro names: 12117 EXIT_FAILURE Unsuccessful termination for exit( ); evaluates to a non-zero value. 12118 EXIT_SUCCESS Successful termination for exit( ); evaluates to 0. 12119 NULL Null pointer. 12120 {RAND_MAX} Maximum value returned by rand( ); at least 32,767. 12121 {MB_CUR_MAX} Integer expression whose value is the maximum number of bytes in a 12122 character specified by the current locale. 12123 The following data types shall be defined through typedef: 12124 div_t Structure type returned by the div( ) function. 12125 ldiv_t Structure type returned by the ldiv( ) function. | 12126 lldiv_t Structure type returned by the lldiv( ) function. | 12127 size_t As described in . 12128 wchar_t As described in . 12129 In addition, the following symbolic names and macros shall be defined as in , for 12130 use in decoding the return value from system( ): 12131 XSI WNOHANG 12132 WUNTRACED 12133 WEXITSTATUS 12134 WIFEXITED 12135 WIFSIGNALED 12136 WIFSTOPPED 12137 WSTOPSIG 12138 WTERMSIG 12139 12140 The following shall be declared as functions and may also be defined as macros. Function 12141 prototypes shall be provided for use with an ISO C standard compiler. 12142 void _Exit(int); 12143 XSI long a64l(const char *); 12144 void abort(void); 12145 int abs(int); 12146 int atexit(void (*)(void)); 12147 double atof(const char *); 12148 int atoi(const char *); 12149 long atol(const char *); 362 Technical Standard (2000) (Draft July 28, 2000) Headers 12150 long long atoll(const char *); 12151 void *bsearch(const void *, const void *, size_t, size_t, 12152 int (*)(const void *, const void *)); 12153 void *calloc(size_t, size_t); 12154 div_t div(int, int); 12155 XSI double drand48(void); 12156 char *ecvt(double, int, int *restrict, int *restrict); (LEGACY) 12157 double erand48(unsigned short[3]); 12158 void exit(int); 12159 XSI char *fcvt(double, int, int *restrict, int *restrict); (LEGACY) 12160 void free(void *); 12161 XSI char *gcvt(double, int, char *); (LEGACY) 12162 char *getenv(const char *); 12163 XSI int getsubopt(char **, char *const *, char **); 12164 int grantpt(int); 12165 char *initstate(unsigned, char *, size_t); 12166 long jrand48(unsigned short[3]); 12167 char *l64a(long); 12168 long labs(long); 12169 XSI void lcong48(unsigned short[7]); 12170 ldiv_t ldiv(long, long); 12171 long long llabs(long long); 12172 XSI long lrand48(void); 12173 void *malloc(size_t); 12174 int mblen(const char *, size_t); 12175 size_t mbstowcs(wchar_t *restrict, const char *restrict, size_t); 12176 int mbtowc(wchar_t *restrict, const char *restrict, size_t); 12177 XSI char *mktemp(char *); (LEGACY) 12178 int mkstemp(char *); 12179 long mrand48(void); 12180 long nrand48(unsigned short[3]); 12181 ADV int posix_memalign(void **, size_t, size_t); 12182 XSI char *ptsname(int); 12183 int putenv(char *); 12184 void qsort(void *, size_t, size_t, int (*)(const void *, 12185 const void *)); 12186 int rand(void); 12187 TSF int rand_r(unsigned *); 12188 XSI long random(void); 12189 void *realloc(void *, size_t); 12190 XSI char *realpath(const char *restrict, char *restrict); 12191 unsigned short seed48(unsigned short[3]); 12192 int setenv(const char *, const char *, int); 12193 void setkey(const char *); 12194 char *setstate(const char *); 12195 void srand(unsigned); 12196 XSI void srand48(long); 12197 void srandom(unsigned); 12198 double strtod(const char *restrict, char **restrict); 12199 float strtof(const char *restrict, char **restrict); 12200 long strtol(const char *restrict, char **restrict, int); 12201 long double strtold(const char *restrict, char **restrict); Base Definitions, Issue 6 363 Headers 12202 long long strtoll(const char *restrict, char **restrict, int); 12203 unsigned long strtoul(const char *restrict, char **restrict, int); 12204 long long strtoull(const char *restrict, char **restrict, int); 12205 int system(const char *); 12206 XSI int unlockpt(int); 12207 int unsetenv(const char *); 12208 size_t wcstombs(char *restrict, const wchar_t *restrict, size_t); 12209 int wctomb(char *, wchar_t); 12210 XSI Inclusion of the header may also make visible all symbols from , 12211 , , and . 12212 APPLICATION USAGE 12213 None. 12214 RATIONALE 12215 None. 12216 FUTURE DIRECTIONS 12217 None. 12218 SEE ALSO 12219 , the System Interfaces volume of IEEE Std. 1003.1-200x, _Exit( ), a64l( ), abort( ), | 12220 abs( ), atexit( ), atof( ), atoi( ), atol( ), atoll( ), bsearch( ), calloc( ), div( ), drand48( ), erand48( ), exit( ), | 12221 free( ), getenv( ), getsubopt( ), grantpt( ), initstate( ), jrand48( ), l64a( ), labs( ), lcong48( ), ldiv( ), llabs( ), | 12222 lldiv( ), lrand48( ), malloc( ), mblen( ), mbstowcs( ), mbtowc( ), mkstemp( ), mrand48( ), nrand48( ), | 12223 posix_memalign( ), ptsname( ), putenv( ), qsort( ), rand( ), realloc( ), realpath( ), setstate( ), srand( ), 12224 srand48( ), srandom( ), strtod( ), strtof( ), strtol( ), strtold( ), strtoll( ), strtoul( ), strtoull( ), unlockpt( ), | 12225 wcstombs( ), wctomb( ) 12226 CHANGE HISTORY 12227 First released in Issue 3. 12228 Issue 4 12229 A reference is added to and for the definition of size_t. 12230 A reference is added to for definitions of the symbolic names and macros defined 12231 for decoding the return value from the system( ) function. This reference and the symbolic names 12232 and macros are marked as an extension. 12233 The names drand48( ), erand48( ), jrand48( ), lcong48( ), lrand48( ), mrand48( ), nrand48( ), putenv( ), 12234 seed48( ), setkey( ), and srand48( ) are added to the list of functions declared in this header and 12235 marked as extensions. 12236 A warning is added indicating that inclusion of may also make visible all symbols 12237 from , , , and . 12238 The APPLICATION USAGE section is removed. 12239 The following changes are incorporated for alignment with the ISO C standard: 12240 * The function declarations in this header are expanded to full ISO C standard prototypes. 12241 * The maximum value of {RAND_MAX} is defined. 12242 * The name {MB_CUR_MAX} is added to the list of macro names defined in this header, while 12243 div_t and ldiv_t are added to the list of defined types. 12244 * The names atexit( ), div( ), labs( ), ldiv( ), mblen( ), mbstowcs( ), mbtowc( ), strtoul( ), wcstombs( ), 12245 and wctomb( ) are added to the list of functions declared in this header. 364 Technical Standard (2000) (Draft July 28, 2000) Headers 12246 Issue 4, Version 2 12247 For X/OPEN UNIX conformance, the a64l( ), ecvt( ), fcvt( ), gcvt( ), getsubopt( ), grantpt( ), 12248 initstate( ), l64a( ), mktemp( ), mkstemp( ), ptsname( ), random( ), realpath( ), setstate( ), srandom( ), 12249 ttyslot( ), unlockpt( ), and valloc( ) functions are added to the list of functions declared in this 12250 header. 12251 Issue 5 12252 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 12253 The ttyslot( ) and valloc( ) functions are marked LEGACY. 12254 The type of the third argument to initstate( ) is changed from int to size_t. The type of the return 12255 value from setstate( ) is changed from char to char*, and the type of the first argument is changed 12256 from char* to const char*. 12257 Issue 6 12258 The Open Group corrigenda item U021/1 has been applied, correcting the prototype for 12259 realpath( ) to be consistent with the reference page. 12260 The Open Group corrigenda item U028/13 has been applied, correcting the prototype for 12261 putenv( ) to be consistent with the reference page. 12262 The rand_r( ) function is marked as part of the _POSIX_THREAD_SAFE_FUNCTIONS option. 12263 Function prototypes for setenv( ) and unsetenv( ) are added. 12264 The posix_memalign( ) function is added for alignment with IEEE Std. 1003.1d-1999. | 12265 This reference page is updated to align with the ISO/IEC 9899: 1999 standard. | 12266 The ecvt( ), fcvt( ), gcvt( ), and mktemp( ) functions are marked LEGACY. | Base Definitions, Issue 6 365 Headers 12267 NAME 12268 string.h - string operations 12269 SYNOPSIS 12270 #include 12271 DESCRIPTION 12272 CX The functionality described on this reference page extends the ISO C standard. Applications 12273 shall define the appropriate feature test macro (see the System Interfaces volume of 12274 IEEE Std. 1003.1-200x, Section 2.2, The Compilation Environment) to enable the visibility of 12275 symbols in this header. 12276 The header shall define the following: 12277 NULL Null pointer constant. 12278 size_t As described in . 12279 The following shall be declared as functions and may also be defined as macros. Function 12280 prototypes shall be provided for use with an ISO C standard compiler. 12281 XSI void *memccpy(void *restrict, const void *restrict, int, size_t); 12282 void *memchr(const void *, int, size_t); 12283 int memcmp(const void *, const void *, size_t); 12284 void *memcpy(void *restrict, const void *restrict, size_t); 12285 void *memmove(void *, const void *, size_t); 12286 void *memset(void *, int, size_t); 12287 char *strcat(char *restrict, const char *restrict); 12288 char *strchr(const char *, int); 12289 int strcmp(const char *, const char *); 12290 int strcoll(const char *, const char *); 12291 char *strcpy(char *restrict, const char *restrict); 12292 size_t strcspn(const char *, const char *); 12293 XSI char *strdup(const char *); 12294 char *strerror(int); 12295 size_t strlen(const char *); 12296 char *strncat(char *restrict, const char *restrict, size_t); 12297 int strncmp(const char *, const char *, size_t); 12298 char *strncpy(char *restrict, const char *restrict, size_t); 12299 char *strpbrk(const char *, const char *); 12300 char *strrchr(const char *, int); 12301 size_t strspn(const char *, const char *); 12302 char *strstr(const char *, const char *); 12303 char *strtok(char *restrict, const char *restrict); 12304 TSF char *strtok_r(char *, const char *, char **); 12305 size_t strxfrm(char *restrict, const char *restrict, size_t); 12306 XSI Inclusion of the header may also make visible all symbols from . 366 Technical Standard (2000) (Draft July 28, 2000) Headers 12307 APPLICATION USAGE 12308 None. 12309 RATIONALE 12310 None. 12311 FUTURE DIRECTIONS 12312 None. 12313 SEE ALSO 12314 , the System Interfaces volume of IEEE Std. 1003.1-200x, memccpy( ), memchr( ), 12315 memcmp( ), memcpy( ), memmove( ), memset( ), strcat( ), strchr( ), strcmp( ), strcoll( ), strcpy( ), 12316 strcspn( ), strdup( ), strerror( ), strlen( ), strncat( ), strncmp( ), strncpy( ), strpbrk( ), strrchr( ), strspn( ), 12317 strstr( ), strtok( ), strxfrm( ) 12318 CHANGE HISTORY 12319 First released in Issue 1. Derived from Issue 1 of the SVID. | 12320 Issue 4 12321 A reference is added to for the definition of size_t. 12322 The memccpy( ) function is marked as an extension. 12323 A warning is added indicating that inclusion of may also make visible all symbols 12324 from . 12325 The APPLICATION USAGE section is removed. 12326 The following changes are incorporated for alignment with the ISO C standard: 12327 * The function declarations in this header are expanded to full ISO C standard prototypes. 12328 * The name memmove( ) is added to the list of functions declared in this header. 12329 Issue 4, Version 2 12330 For X/OPEN UNIX conformance, the strdup( ) function is added to the list of functions declared 12331 in this header. 12332 Issue 5 12333 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 12334 Issue 6 12335 The strtok_r( ) function is marked as part of the _POSIX_THREAD_SAFE_FUNCTIONS option. | 12336 This reference page is updated to align with the ISO/IEC 9899: 1999 standard. | Base Definitions, Issue 6 367 Headers 12337 NAME 12338 strings.h - string operations 12339 SYNOPSIS 12340 XSI #include 12341 12342 DESCRIPTION 12343 The following shall be declared as functions and may also be defined as macros. Function 12344 prototypes shall be provided for use with an ISO C standard compiler. 12345 int bcmp(const void *, const void *, size_t); (LEGACY) 12346 void bcopy(const void *, void *, size_t); (LEGACY) 12347 void bzero(void *, size_t); (LEGACY) 12348 int ffs(int); 12349 char *index(const char *, int); (LEGACY) 12350 char *rindex(const char *, int); (LEGACY) 12351 int strcasecmp(const char *, const char *); 12352 int strncasecmp(const char *, const char *, size_t); 12353 The size_t type shall be defined through typedef as described in . 12354 APPLICATION USAGE 12355 None. 12356 RATIONALE 12357 None. 12358 FUTURE DIRECTIONS 12359 None. 12360 SEE ALSO 12361 , the System Interfaces volume of IEEE Std. 1003.1-200x, ffs( ), strcasecmp( ), | 12362 strncasecmp( ) | 12363 CHANGE HISTORY 12364 First released in Issue 4, Version 2. 12365 Issue 6 12366 The Open Group corrigenda item U021/2 has been applied, correcting the prototype for index( ) 12367 to be consistent with the reference page. | 12368 The bcmp( ), bcopy( ), bzero( ), index( ), and rindex( ) functions are marked LEGACY. | 368 Technical Standard (2000) (Draft July 28, 2000) Headers 12369 NAME 12370 stropts.h - STREAMS interface (STREAMS) 12371 SYNOPSIS 12372 XSR #include 12373 12374 DESCRIPTION 12375 The header shall define the bandinfo structure that includes at least the following 12376 members: 12377 unsigned char bi_pri 12378 int bi_flag 12379 The header shall define the strpeek structure that includes at least the following 12380 members: 12381 struct strbuf ctlbuf 12382 struct strbuf databuf 12383 t_uscalar_t flags 12384 The header shall define the strbuf structure that includes at least the following 12385 members: 12386 int maxlen Maximum buffer length. 12387 int len Length of data. 12388 char *buf Pointer to buffer. 12389 The header shall define the strfdinsert structure that includes at least the following 12390 members: 12391 struct strbuf ctlbuf 12392 struct strbuf databuf 12393 t_uscalar_t flags 12394 int fildes 12395 int offset 12396 The header shall define the strioctl structure that includes at least the following 12397 members: 12398 int ic_cmd 12399 int ic_timout 12400 int ic_len 12401 char *ic_dp 12402 The header shall define the strrecvfd structure that includes at least the following 12403 members: 12404 int fd 12405 uid_t uid 12406 gid_t gid 12407 The uid_t and gid_t types shall be defined through typedef as described in . 12408 The t_uscalar_t type shall be defined as described in the referenced XNS, Issue 5 specification, | 12409 . 12410 The header shall define the str_list structure that includes at least the following 12411 members: Base Definitions, Issue 6 369 Headers 12412 int sl_nmods 12413 struct str_mlist *sl_modlist 12414 The header shall define the str_mlist structure that includes at least the following 12415 member: 12416 char l_name[FMNAMESZ+1] 12417 At least the following macros shall be defined for use as the request argument to ioctl( ): 12418 I_PUSH Push STREAMS module onto the top of the current STREAM, just below the 12419 STREAM head. 12420 I_POP Remove STREAMS module from just below the STREAM head. 12421 I_LOOK Retrieve the name of the module just below the STREAM head and place it in 12422 a character string. At least the following macros shall be defined for use as the 12423 arg argument: 12424 FMNAMESZ The minimum size in bytes of the buffer referred to by the 12425 arg argument. 12426 I_FLUSH This request flushes all input and/or output queues, depending on the value 12427 of the arg argument. At least the following macros shall be defined for use as 12428 the arg argument: 12429 FLUSHR Flush read queues. 12430 FLUSHW Flush write queues. 12431 FLUSHRW Flush read and write queues. 12432 I_FLUSHBAND Flush only band specified. 12433 I_SETSIG Informs the STREAM head that the process wants the SIGPOLL signal issued 12434 (see signal( )) when a particular event has occurred on the STREAM. 12435 The header shall define the following possible values for arg when 12436 I_SETSIG is specified: 12437 S_RDNORM A normal (priority band set to 0) message has arrived at the 12438 head of a STREAM head read queue. 12439 S_RDBAND A message with a non-zero priority band has arrived at the 12440 head of a STREAM head read queue. 12441 S_INPUT A message, other than a high-priority message, has arrived 12442 at the head of a STREAM head read queue. 12443 S_HIPRI A high-priority message is present on a STREAM head read 12444 queue. 12445 S_OUTPUT The write queue for normal data (priority band 0) just 12446 below the STREAM head is no longer full. This notifies the 12447 process that there is room on the queue for sending (or 12448 writing) normal data downstream. 12449 S_WRNORM Same as S_OUTPUT. 12450 S_WRBAND The write queue for a non-zero priority band just below the 12451 STREAM head is no longer full. 370 Technical Standard (2000) (Draft July 28, 2000) Headers 12452 S_MSG A STREAMS signal message that contains the SIGPOLL 12453 signal reaches the front of the STREAM head read queue. 12454 S_ERROR Notification of an error condition reaches the STREAM 12455 head. 12456 S_HANGUP Notification of a hangup reaches the STREAM head. 12457 S_BANDURG When used in conjunction with S_RDBAND, SIGURG is 12458 generated instead of SIGPOLL when a priority message 12459 reaches the front of the STREAM head read queue. 12460 I_GETSIG Returns the events for which the calling process is currently registered to be 12461 sent a SIGPOLL signal. 12462 I_FIND Compares the names of all modules currently present in the STREAM to the 12463 name pointed to by arg. 12464 I_PEEK Allows a process to retrieve the information in the first message on the 12465 STREAM head read queue without taking the message off the queue. At least 12466 the following macros are defined for use as the arg argument: 12467 RS_HIPRI Only look for high-priority messages. 12468 I_SRDOPT Sets the read mode. At least the following macros shall be defined for use as 12469 the arg argument: 12470 RNORM Byte-STREAM mode, the default. 12471 RMSGD Message-discard mode. 12472 RMSGN Message-nondiscard mode. 12473 RPROTNORM Fail read( ) with [EBADMSG] if a message containing a 12474 control part is at the front of the STREAM head read queue. 12475 RPROTDAT Deliver the control part of a message as data when a 12476 process issues a read( ). 12477 RPROTDIS Discard the control part of a message, delivering any data 12478 part, when a process issues a read( ). 12479 I_GRDOPT Returns the current read mode setting. 12480 I_NREAD Counts the number of data bytes in data blocks in the first message on the 12481 STREAM head read queue. 12482 I_FDINSERT Creates a message from the specified buffer(s), adds information about 12483 another STREAM, and sends the message downstream. 12484 I_STR Constructs an internal STREAMS ioctl( ) message and sends that message 12485 downstream. 12486 I_SWROPT Sets the write mode. At least the following macros are defined for use as the 12487 arg argument: 12488 SNDZERO Send a zero-length message downstream when a write( ) of 12489 0 bytes occurs. 12490 I_GWROPT Returns the current write mode setting. 12491 I_SENDFD Requests the STREAM associated with fildes to send a message, containing a 12492 file pointer, to the STREAM head at the other end of a STREAMS pipe. Base Definitions, Issue 6 371 Headers 12493 I_RECVFD Retrieves the file descriptor associated with the message sent by an 12494 I_SENDFD ioctl( ) over a STREAMS pipe. 12495 I_LIST This request allows the process to list all the module names on the STREAM, 12496 up to and including the topmost driver name. 12497 I_ATMARK This request allows the process to see if the current message on the STREAM 12498 head read queue is ``marked'' by some module downstream. At least the 12499 following macros are defined for use as the arg argument: 12500 ANYMARK Check if the message is marked. 12501 LASTMARK Check if the message is the last one marked on the queue. 12502 I_CKBAND Check if the message of a given priority band exists on the STREAM head 12503 read queue. 12504 I_GETBAND Return the priority band of the first message on the STREAM head read 12505 queue. 12506 I_CANPUT Check if a certain band is writable. 12507 I_SETCLTIME Allow the process to set the time the STREAM head delays when a STREAM 12508 is closing and there is data on the write queues. 12509 I_GETCLTIME Returns the close time delay. 12510 I_LINK Connects two STREAMs. 12511 I_UNLINK Disconnects the two STREAMs. The header shall define at least the following 12512 value for arg: 12513 MUXID_ALL Unlink all STREAMs linked to the STREAM associated with 12514 fildes. 12515 I_PLINK Connects two STREAMs with a persistent link. 12516 I_PUNLINK Disconnects the two STREAMs that were connected with a persistent link. 12517 The following macros shall be defined for getmsg( ), getpmsg( ), putmsg( ), and putpmsg( ): 12518 MSG_ANY Receive any message. 12519 MSG_BAND Receive message from specified band. 12520 MSG_HIPRI Send/receive high-priority message. 12521 MORECTL More control information is left in message. 12522 MOREDATA More data is left in message. 12523 The header may make visible all of the symbols from . 12524 The following shall be declared as functions in the header and may also be defined 12525 as macros. Function prototypes shall be provided for use with an ISO C standard compiler. 12526 int isastream(int); 12527 int getmsg(int, struct strbuf *restrict, struct strbuf *restrict, 12528 int *restrict); 12529 int getpmsg(int, struct strbuf *restrict, struct strbuf *restrict, 12530 int *restrict, int *restrict); 12531 int ioctl(int, int, ... ); 12532 int putmsg(int, const struct strbuf *, const struct strbuf *, int); 12533 int putpmsg(int, const struct strbuf *, const struct strbuf *, int, 372 Technical Standard (2000) (Draft July 28, 2000) Headers 12534 int); 12535 int fattach(int, const char *); 12536 int fdetach(const char *); 12537 APPLICATION USAGE 12538 None. 12539 RATIONALE 12540 None. 12541 FUTURE DIRECTIONS 12542 None. 12543 SEE ALSO 12544 , the System Interfaces volume of IEEE Std. 1003.1-200x, close( ), fcntl( ), getmsg( ), 12545 ioctl( ), open( ), pipe( ), read( ), poll( ), putmsg( ), signal( ), write( ) the XNS, Issue 5 specification, | 12546 12547 CHANGE HISTORY 12548 First released in Issue 4, Version 2. 12549 Issue 5 12550 The flags member of the strpeek and strfdinsert structures are changed from type long to 12551 t_uscalar_t. 12552 Issue 6 12553 This header is marked as part of the XSI STREAMS Option Group. | 12554 The restrict keyword is added to the prototypes for getmsg( ) and getpmsg( ). | Base Definitions, Issue 6 373 Headers 12555 NAME 12556 sys/ipc.h - XSI interprocess communication access structure 12557 SYNOPSIS 12558 XSI #include 12559 12560 DESCRIPTION 12561 The header is used by three mechanisms for XSI interprocess communication (IPC): 12562 messages, semaphores, and shared memory. All use a common structure type, ipc_perm to pass 12563 information used in determining permission to perform an IPC operation. 12564 The ipc_perm structure shall contain the following members: 12565 uid_t uid Owner's user ID. 12566 gid_t gid Owner's group ID. 12567 uid_t cuid Creator's user ID. 12568 gid_t cgid Creator's group ID. 12569 mode_t mode Read/write permission. 12570 The uid_t, gid_t, mode_t, and key_t types shall be defined as described in . 12571 Definitions shall be provided for the following constants: 12572 Mode bits: 12573 IPC_CREAT Create entry if key does not exist. 12574 IPC_EXCL Fail if key exists. 12575 IPC_NOWAIT Error if request must wait. 12576 Keys: 12577 IPC_PRIVATE Private key. 12578 Control commands: 12579 IPC_RMID Remove identifier. 12580 IPC_SET Set options. 12581 IPC_STAT Get options. 12582 The following shall be declared as a function and may also be defined as a macro. Function 12583 prototypes shall be provided for use with an ISO C standard compiler. 12584 key_t ftok(const char *, int); 12585 APPLICATION USAGE 12586 None. 12587 RATIONALE 12588 None. 12589 FUTURE DIRECTIONS 12590 None. 12591 SEE ALSO 12592 , the System Interfaces volume of IEEE Std. 1003.1-200x, ftok( ) 374 Technical Standard (2000) (Draft July 28, 2000) Headers 12593 CHANGE HISTORY 12594 First released in Issue 2. Derived from System V Release 2.0. | 12595 Issue 4 12596 The DESCRIPTION is corrected to say that the header ``is used by three mechanisms . . .''. 12597 Reference to the header is added for the definitions of uid_t, gid_t, and mode_t. 12598 Issue 4, Version 2 12599 For X/OPEN UNIX conformance, the ftok( ) function is added to the list of functions declared in 12600 this header. Base Definitions, Issue 6 375 Headers 12601 NAME 12602 sys/mman.h - memory management declarations | 12603 SYNOPSIS 12604 #include 12605 DESCRIPTION 12606 The header shall be supported if the implementation supports at least one of the 12607 following options: 12608 MF * The Memory Mapped Files option 12609 SHM * The Shared Memory Objects option 12610 ML * The Process Memory Locking option 12611 MPR * The Memory Protection option 12612 TYM * The Typed Memory Objects option 12613 SIO * The Synchronized Input and Output option | 12614 ADV * The Advisory Information option | 12615 TYM * The Typed Memory Objects option | 12616 The following protection options shall be defined: | 12617 code2 PROT_READ Page can be read. 12618 code2 PROT_WRITE Page can be written. 12619 code2 PROT_EXEC Page can be executed. 12620 code2 PROT_NONE Page cannot be accessed. 12621 The following flag options shall be defined: | 12622 MF|SHM MAP_SHARED Share changes. 12623 MF|SHM MAP_PRIVATE Changes are private. 12624 MF|SHM MAP_FIXED Interpret addr exactly. 12625 The following flags shall be defined for msync( ): 12626 MF|SIO MS_ASYNC Perform asynchronous writes. 12627 MF|SIO MS_SYNC Perform synchronous writes. 12628 MF|SIO MS_INVALIDATE Invalidate mappings. 12629 ML The following symbolic constants shall be defined for the mlockall( ) function: | 12630 ML MCL_CURRENT Lock currently mapped pages. 12631 ML MCL_FUTURE Lock pages that become mapped. 12632 MF|SHM The symbolic constant MAP_FAILED shall be defined to indicate a failure from the mmap( ) 12633 function. 12634 code1 Values for advice used by posix_madvise( ) are as follows: | 12635 POSIX_MADV_NORMAL 12636 The application has no advice to give on its behavior with respect to the specified range. It 12637 is the default characteristic if no advice is given for a range of memory. 376 Technical Standard (2000) (Draft July 28, 2000) Headers 12638 POSIX_MADV_SEQUENTIAL 12639 The application expects to access the specified range sequentially from lower addresses to 12640 higher addresses. 12641 POSIX_MADV_RANDOM 12642 The application expects to access the specified range in a random order. 12643 POSIX_MADV_WILLNEED 12644 The application expects to access the specified range in the near future. 12645 POSIX_MADV_DONTNEED 12646 The application expects that it will not access the specified range in the near future. 12647 12648 TYM The following flags shall be defined for posix_typed_mem_open( ): | 12649 POSIX_TYPED_MEM_ALLOCATE 12650 Allocate on mmap( ). 12651 POSIX_TYPED_MEM_ALLOCATE_CONTIG 12652 Allocate contiguously on mmap( ). 12653 POSIX_TYPED_MEM_MAP_ALLOCATABLE Map on mmap( ), without affecting allocatability. 12654 12655 The mode_t, off_t, and size_t types shall be defined as described in . 12656 TYM The header shall define the structure posix_typed_mem_info, which includes at 12657 least the following member: 12658 size_t posix_tmi_length Maximum length which may be allocated 12659 from a typed memory object. 12660 12661 The following shall be declared in as functions and may also be defined as 12662 macros. Function prototypes shall be provided for use with an ISO C standard compiler. 12663 ML int mlock(const void *, size_t); 12664 int mlockall(int); 12665 MF|SHM void *mmap(void *, size_t, int, int, int, off_t); 12666 MPR int mprotect(void *, size_t, int); 12667 MF|SIO int msync(void *, size_t, int); 12668 ML int munlock(const void *, size_t); 12669 int munlockall(void); 12670 MF|SHM int munmap(void *, size_t); 12671 ADV int posix_madvise(void *, size_t, int); 12672 TYM int posix_mem_offset(const void *restrict, size_t, off_t *restrict, 12673 size_t *restrict, int *restrict); 12674 int posix_typed_mem_get_info(int, struct posix_typed_mem_info *); 12675 int posix_typed_mem_open(const char *, int, int); 12676 SHM int shm_open(const char *, int, mode_t); 12677 int shm_unlink(const char *); 12678 Base Definitions, Issue 6 377 Headers 12679 APPLICATION USAGE 12680 None. 12681 RATIONALE 12682 None. 12683 FUTURE DIRECTIONS 12684 None. 12685 SEE ALSO 12686 , the System Interfaces volume of IEEE Std. 1003.1-200x, mlock( ), mlockall( ), 12687 mmap( ), mprotect( ), msync( ), munlock( ), munlockall( ), munmap( ), posix_mem_offset( ), 12688 posix_typed_mem_get_info( ), posix_typed_mem_open( ), shm_open( ), shm_unlink( ) 12689 CHANGE HISTORY 12690 First released in Issue 4, Version 2. 12691 Issue 5 12692 Updated for alignment with the POSIX Realtime Extension. 12693 Issue 6 12694 The header is marked as dependent on support for either the 12695 _POSIX_MAPPED_FILES, _POSIX_MEMLOCK, or _POSIX_SHARED_MEMORY options. 12696 The following changes are made for alignment with IEEE Std. 1003.1j-2000: 12697 * The TYM margin code is added to the list of margin codes for the header line, 12698 as well as for other lines. 12699 * The POSIX_TYPED_MEM_ALLOCATE, POSIX_TYPED_MEM_ALLOCATE_CONTIG, and 12700 POSIX_TYPED_MEM_MAP_ALLOCATABLE flags are added. 12701 * The posix_tmi_length structure is added. 12702 * The posix_mem_offset( ), posix_typed_mem_get_info( ), and posix_typed_mem_open( ) functions 12703 are added. 12704 The restrict keyword is added to the prototype for posix_mem_offset( ). | 12705 IEEE PASC Interpretation 1003.1 #102 is applied adding the prototype for posix_madvise( ). | 378 Technical Standard (2000) (Draft July 28, 2000) Headers 12706 NAME 12707 sys/msg.h - XSI message queue structures 12708 SYNOPSIS 12709 XSI #include 12710 12711 DESCRIPTION 12712 The header shall define the following constant and members of the structure 12713 msqid_ds. 12714 The following data types shall be defined through typedef: 12715 msgqnum_t Used for the number of messages in the message queue. 12716 msglen_t Used for the number of bytes allowed in a message queue. 12717 These types shall be unsigned integer types that are able to store values at least as large as a type 12718 unsigned short. 12719 Message operation flag: 12720 MSG_NOERROR No error if big message. 12721 The msqid_ds structure shall contain the following members: 12722 struct ipc_perm msg_perm Operation permission structure. 12723 msgqnum_t msg_qnum Number of messages currently on queue. 12724 msglen_t msg_qbytes Maximum number of bytes allowed on queue. 12725 pid_t msg_lspid Process ID of last msgsnd( ). 12726 pid_t msg_lrpid Process ID of last msgrcv( ). 12727 time_t msg_stime Time of last msgsnd( ). 12728 time_t msg_rtime Time of last msgrcv( ). 12729 time_t msg_ctime Time of last change. 12730 The pid_t, time_t, key_t, size_t, and ssize_t types shall be defined as described in . 12731 The following shall be declared as functions and may also be defined as macros. Function 12732 prototypes shall be provided for use with an ISO C standard compiler. 12733 int msgctl(int, int, struct msqid_ds *); 12734 int msgget(key_t, int); 12735 ssize_t msgrcv(int, void *, size_t, long, int); 12736 int msgsnd(int, const void *, size_t, int); 12737 In addition, all of the symbols from shall be defined when this header is included. 12738 APPLICATION USAGE 12739 None. 12740 RATIONALE 12741 None. 12742 FUTURE DIRECTIONS 12743 None. 12744 SEE ALSO 12745 , msgctl( ), msgget( ), msgrcv( ), msgsnd( ) Base Definitions, Issue 6 379 Headers 12746 CHANGE HISTORY 12747 First released in Issue 2. Derived from System V Release 2.0. | 12748 Issue 4 12749 The function declarations in this header are expanded to full ISO C standard prototypes. 12750 Reference to the header is added for the definitions of pid_t, time_t, key_t, and 12751 size_t. 12752 A statement is added indicating that all symbols in are defined when this header is 12753 included. 380 Technical Standard (2000) (Draft July 28, 2000) Headers 12754 NAME 12755 sys/resource.h - definitions for XSI resource operations 12756 SYNOPSIS 12757 XSI #include 12758 12759 DESCRIPTION 12760 The header shall define the following symbolic constants as possible values of 12761 the which argument of getpriority( ) and setpriority( ): 12762 PRIO_PROCESS Identifies the who argument as a process ID. 12763 PRIO_PGRP Identifies the who argument as a process group ID. 12764 PRIO_USER Identifies the who argument as a user ID. 12765 The following type shall be defined through typedef: 12766 rlim_t Unsigned integer type used for limit values. | 12767 The following symbolic constants shall be defined: 12768 RLIM_INFINITY A value of rlim_t indicating no limit. 12769 RLIM_SAVED_MAX A value of type rlim_t indicating an unrepresentable saved hard 12770 limit. 12771 RLIM_SAVED_CUR A value of type rlim_t indicating an unrepresentable saved soft limit. 12772 On implementations where all resource limits are representable in an object of type rlim_t, 12773 RLIM_SAVED_MAX and RLIM_SAVED_CUR need not be distinct from RLIM_INFINITY. 12774 The following symbolic constants shall be defined as possible values of the who parameter of 12775 getrusage( ): 12776 RUSAGE_SELF Returns information about the current process. 12777 RUSAGE_CHILDREN Returns information about children of the current process. 12778 The header shall define the rlimit structure that includes at least the following 12779 members: 12780 rlim_t rlim_cur The current (soft) limit. 12781 rlim_t rlim_max The hard limit. 12782 The header shall define the rusage structure that includes at least the following 12783 members: 12784 struct timeval ru_utime User time used. 12785 struct timeval ru_stime System time used. 12786 The timeval structure shall be defined as described in . 12787 The following symbolic constants shall be defined as possible values for the resource argument of 12788 getrlimit( ) and setrlimit( ): 12789 RLIMIT_CORE Limit on size of core dump file. 12790 RLIMIT_CPU Limit on CPU time per process. 12791 RLIMIT_DATA Limit on data segment size. 12792 RLIMIT_FSIZE Limit on file size. Base Definitions, Issue 6 381 Headers 12793 RLIMIT_NOFILE Limit on number of open files. 12794 RLIMIT_STACK Limit on stack size. 12795 RLIMIT_AS Limit on address space size. 12796 The following are declared as functions and may also be defined as macros. Function prototypes 12797 shall be provided for use with an ISO C standard compiler. 12798 int getpriority(int, id_t); 12799 int getrlimit(int, struct rlimit *); 12800 int getrusage(int, struct rusage *); 12801 int setpriority(int, id_t, int); 12802 int setrlimit(int, const struct rlimit *); 12803 The id_t type shall be defined through typedef as described in . 12804 Inclusion of the header may also make visible all symbols from . 12805 APPLICATION USAGE 12806 None. 12807 RATIONALE 12808 None. 12809 FUTURE DIRECTIONS 12810 None. 12811 SEE ALSO 12812 , , the System Interfaces volume of IEEE Std. 1003.1-200x, 12813 getpriority( ), getrusage( ), getrlimit( ) 12814 CHANGE HISTORY 12815 First released in Issue 4, Version 2. 12816 Issue 5 | 12817 Large File System extensions are added. 382 Technical Standard (2000) (Draft July 28, 2000) Headers 12818 NAME | 12819 sys/select.h - select types | 12820 SYNOPSIS | 12821 #include | 12822 DESCRIPTION | 12823 The header shall define the timeval structure that includes at least the following | 12824 members: | 12825 time_t tv_sec Seconds. | 12826 suseconds_t tv_usec Microseconds. | 12827 The time_t and suseconds_t types shall be defined as described in . | 12828 The sigset_t type shall be defined as described in . | 12829 The timespec structure shall be defined as described in . | 12830 The header shall define the fd_set type as a structure that includes at least the | 12831 following member: | 12832 long fds_bits[] Bit mask for open file descriptions. | 12833 Each of the following may be declared as a function, or defined as a macro, or both: | 12834 void FD_CLR(int fd, fd_set *fdset) | 12835 Clears the bit for the file descriptor fd in the file descriptor set fdset. | 12836 int FD_ISSET(int fd, fd_set *fdset) | 12837 Returns a non-zero value if the bit for the file descriptor fd is set in the file descriptor set by | 12838 fdset, and 0 otherwise. | 12839 void FD_SET(int fd, fd_set *fdset) | 12840 Sets the bit for the file descriptor fd in the file descriptor set fdset. | 12841 void FD_ZERO(fd_set *fdset) | 12842 Initializes the file descriptor set fdset to have zero bits for all file descriptors. | 12843 FD_SETSIZE | 12844 Maximum number of file descriptors in an fd_set structure. | 12845 If implemented as macros, these may evaluate their arguments more than once, so applications | 12846 should ensure that the arguments they supply are never expressions with side effects. | 12847 The following shall be declared as functions and may also be defined as macros. Function | 12848 prototypes shall be provided for use with an ISO C standard compiler. | 12849 int pselect(int, fd_set *, fd_set *, fd_set *, const struct timespec *, | 12850 const sigset_t *); | 12851 int select(int, fd_set *, fd_set *, fd_set *, struct timeval *); | 12852 Inclusion of the header may make visible all symbols from the headers | 12853 , , and . | Base Definitions, Issue 6 383 Headers 12854 APPLICATION USAGE | 12855 None. | 12856 RATIONALE | 12857 None. | 12858 FUTURE DIRECTIONS | 12859 None. | 12860 SEE ALSO | 12861 , , , , the System Interfaces volume of | 12862 IEEE Std. 1003.1-200x, pselect( ), select( ) | 12863 CHANGE HISTORY || 12864 First released in Issue 6. Derived from IEEE Std. 1003.1g-2000. | 384 Technical Standard (2000) (Draft July 28, 2000) Headers 12865 NAME 12866 sys/sem.h - XSI semaphore facility 12867 SYNOPSIS 12868 XSI #include 12869 12870 DESCRIPTION 12871 The header shall define the following constants and structures. 12872 Semaphore operation flags: 12873 SEM_UNDO Set up adjust on exit entry. 12874 Command definitions for the semctl( ) function shall be provided as follows: 12875 GETNCNT Get semncnt. 12876 GETPID Get sempid. 12877 GETVAL Get semval. 12878 GETALL Get all cases of semval. 12879 GETZCNT Get semzcnt. 12880 SETVAL Set semval. 12881 SETALL Set all cases of semval. 12882 The semid_ds structure shall contain the following members: 12883 struct ipc_perm sem_perm Operation permission structure. 12884 unsigned short sem_nsems Number of semaphores in set. 12885 time_t sem_otime Last semop( ) time. 12886 time_t sem_ctime Last time changed by semctl( ). 12887 The pid_t, time_t, key_t, and size_t types shall be defined as described in . 12888 A semaphore shall be represented by an anonymous structure containing the following 12889 members: 12890 unsigned short semval Semaphore value. 12891 pid_t sempid Process ID of last operation. 12892 unsigned short semncnt Number of processes waiting for semval 12893 to become greater than current value. 12894 unsigned short semzcnt Number of processes waiting for semval 12895 to become 0. 12896 The sembuf structure shall contain the following members: 12897 unsigned short sem_num Semaphore number. 12898 short sem_op Semaphore operation. 12899 short sem_flg Operation flags. 12900 The following shall be declared as functions and may also be defined as macros. Function 12901 prototypes shall be provided for use with an ISO C standard compiler. 12902 int semctl(int, int, int, ...); 12903 int semget(key_t, int, int); 12904 int semop(int, struct sembuf *, size_t); Base Definitions, Issue 6 385 Headers 12905 In addition, all of the symbols from shall be defined when this header is included. 12906 APPLICATION USAGE 12907 None. 12908 RATIONALE 12909 None. 12910 FUTURE DIRECTIONS 12911 None. 12912 SEE ALSO 12913 , semctl( ), semget( ), semop( ) 12914 CHANGE HISTORY 12915 First released in Issue 2. Derived from System V Release 2.0. | 12916 Issue 4 12917 The function declarations in this header are expanded to full ISO C standard prototypes. 12918 Reference to the header is added for the definitions of pid_t, time_t, key_t, and 12919 size_t. 12920 A statement is added indicating that all symbols in are defined when this header is 12921 included. 386 Technical Standard (2000) (Draft July 28, 2000) Headers 12922 NAME 12923 sys/shm.h - XSI shared memory facility 12924 SYNOPSIS 12925 XSI #include 12926 12927 DESCRIPTION 12928 The header shall define the following symbolic constants: | 12929 SHM_RDONLY Attach read-only (else read-write). | 12930 SHM_RND Round attach address to SHMLBA. 12931 The header shall define the following symbolic value: | 12932 SHMLBA Segment low boundary address multiple. | 12933 The following data types shall be defined through typedef: | 12934 shmatt_t Unsigned integer used for the number of current attaches that must be able to 12935 store values at least as large as a type unsigned short. 12936 The shmid_ds structure shall contain the following members: 12937 struct ipc_perm shm_perm Operation permission structure. 12938 size_t shm_segsz Size of segment in bytes. 12939 pid_t shm_lpid Process ID of last shared memory operation. 12940 pid_t shm_cpid Process ID of creator. 12941 shmatt_t shm_nattch Number of current attaches. 12942 time_t shm_atime Time of last shmat( ). 12943 time_t shm_dtime Time of last shmdt( ). 12944 time_t shm_ctime Time of last change by shmctl( ). 12945 The pid_t, time_t, key_t, and size_t types shall be defined as described in . 12946 The following shall be declared as functions and may also be defined as macros. Function 12947 prototypes shall be provided for use with an ISO C standard compiler. 12948 void *shmat(int, const void *, int); 12949 int shmctl(int, int, struct shmid_ds *); 12950 int shmdt(const void *); 12951 int shmget(key_t, size_t, int); 12952 In addition, all of the symbols from shall be defined when this header is included. 12953 APPLICATION USAGE 12954 None. 12955 RATIONALE 12956 None. 12957 FUTURE DIRECTIONS 12958 None. 12959 SEE ALSO 12960 , the System Interfaces volume of IEEE Std. 1003.1-200x, shmat( ), shmctl( ), shmdt( ), 12961 shmget( ) Base Definitions, Issue 6 387 Headers 12962 CHANGE HISTORY 12963 First released in Issue 2. Derived from System V Release 2.0. | 12964 Issue 4 12965 The function declarations in this header are expanded to full ISO C standard prototypes. 12966 Reference to the header is added for the definitions of pid_t, time_t, key_t, and 12967 size_t. 12968 A statement is added indicating that all symbols in are defined when this header is 12969 included. 12970 Issue 5 12971 The type of shm_segsz is changed from int to size_t. 388 Technical Standard (2000) (Draft July 28, 2000) Headers 12972 NAME 12973 sys/socket.h - main sockets header 12974 SYNOPSIS 12975 #include 12976 DESCRIPTION 12977 The header shall make available the type, socklen_t, which is an opaque integer | 12978 type of length of at least 32 bits; see APPLICATION USAGE. | 12979 The header shall define the unsigned integer type sa_family_t. | 12980 The header shall define the sockaddr structure that includes at least the 12981 following members: 12982 sa_family_t sa_family Address family. 12983 char sa_data[] Socket address (variable-length data). 12984 The sockaddr structure is used to define a socket address which is used in the bind( ), connect( ), 12985 getpeername( ), getsockname( ), recvfrom( ), and sendto( ) functions. 12986 The header shall define the sockaddr_storage structure. This structure shall be: 12987 * Large enough to accommodate all supported protocol-specific address structures 12988 * Aligned at an appropriate boundary so that pointers to it can be cast as pointers to protocol- 12989 specific address structures and used to access the fields of those structures without 12990 alignment problems 12991 The sockaddr_storage structure shall contain at least the following members: | 12992 sa_family_t ss_family | 12993 When a sockaddr_storage structure is cast as a sockaddr structure, the ss_family field of the | 12994 sockaddr_storage structure maps onto the sa_family field of the sockaddr structure. When a 12995 sockaddr_storage structure is cast as a protocol-specific address structure, the ss_family field 12996 maps onto a field of that structure that is of type sa_family_t and that identifies the protocol's 12997 address family. 12998 The header shall define the msghdr structure that includes at least the following 12999 members: 13000 void *msg_name Optional address. 13001 socklen_t msg_namelen Size of address. 13002 struct iovec *msg_iov Scatter/gather array. 13003 int msg_iovlen Members in msg_iov. 13004 void *msg_control Ancillary data; see below. 13005 socklen_t msg_controllen Ancillary data buffer len. 13006 int msg_flags Flags on received message. 13007 The msghdr structure is used to minimize the number of directly supplied parameters to the 13008 recvmsg( ) and sendmsg( ) functions. This structure is used as a value=result parameter in the 13009 recvmsg( ) function and value only for the sendmsg( ) function. 13010 The iovec structure shall be defined through typedef as described in . 13011 The header shall define the cmsghdr structure that includes at least the following 13012 members: 13013 socklen_t cmsg_len Data byte count, including the cmsghdr. 13014 int cmsg_level Originating protocol. Base Definitions, Issue 6 389 Headers 13015 int cmsg_type Protocol-specific type. 13016 The cmsghdr structure is used for storage of ancillary data object information. 13017 Ancillary data consists of a sequence of pairs, each consisting of a cmsghdr structure followed 13018 by a data array. The data array contains the ancillary data message, and the cmsghdr structure 13019 contains descriptive information that allows an application to correctly parse the data. 13020 The values for cmsg_level shall be legal values for the level argument to the getsockopt( ) and 13021 setsockopt( ) functions. The system documentation shall specify the cmsg_type definitions for the 13022 supported protocols. 13023 Ancillary data is also possible at the socket level. The header defines the 13024 following macro for use as the cmsg_type value when cmsg_level is SOL_SOCKET: 13025 SCM_RIGHTS Indicates that the data array contains the access rights to be sent or 13026 received. 13027 The header defines the following macros to gain access to the data arrays in the 13028 ancillary data associated with a message header: 13029 CMSG_DATA(cmsg) 13030 If the argument is a pointer to a cmsghdr structure, this macro returns an unsigned 13031 character pointer to the data array associated with the cmsghdr structure. 13032 CMSG_NXTHDR(mhdr,cmsg) 13033 If the first argument is a pointer to a msghdr structure and the second argument is a pointer 13034 to a cmsghdr structure in the ancillary data pointed to by the msg_control field of that 13035 msghdr structure, this macro returns a pointer to the next cmsghdr structure, or a null 13036 pointer if this structure is the last cmsghdr in the ancillary data. 13037 CMSG_FIRSTHDR(mhdr) 13038 If the argument is a pointer to a msghdr structure, this macro returns a pointer to the first 13039 cmsghdr structure in the ancillary data associated with this msghdr structure, or a null 13040 pointer if there is no ancillary data associated with the msghdr structure. 13041 The header shall define the linger structure that includes at least the following 13042 members: 13043 int l_onoff Indicates whether linger option is enabled. 13044 int l_linger Linger time, in seconds. 13045 The header shall define the following macros, with distinct integral values: 13046 SOCK_DGRAM Datagram socket. 13047 SOCK_STREAM Byte-stream socket. 13048 SOCK_SEQPACKET Sequenced-packet socket. 13049 The header shall define the following macro for use as the level argument of 13050 setsockopt( ) and getsockopt( ). 13051 SOL_SOCKET Options to be accessed at socket level, not protocol level. 13052 The header shall define the following macros, with distinct integral values, for 13053 use as the option_name argument in getsockopt( ) or setsockopt( ) calls: 13054 SO_ACCEPTCONN Socket is accepting connections. 13055 SO_BROADCAST Transmission of broadcast messages is supported. 390 Technical Standard (2000) (Draft July 28, 2000) Headers 13056 SO_DEBUG Debugging information is being recorded. 13057 SO_DONTROUTE Bypass normal routing. 13058 SO_ERROR Socket error status. 13059 SO_KEEPALIVE Connections are kept alive with periodic messages. 13060 SO_LINGER Socket lingers on close. 13061 SO_OOBINLINE Out-of-band data is transmitted in line. 13062 SO_RCVBUF Receive buffer size. 13063 SO_RCVLOWAT Receive ``low water mark''. 13064 SO_RCVTIMEO Receive timeout. 13065 SO_REUSEADDR Reuse of local addresses is supported. 13066 SO_SNDBUF Send buffer size. 13067 SO_SNDLOWAT Send ``low water mark''. 13068 SO_SNDTIMEO Send timeout. 13069 SO_TYPE Socket type. 13070 The header shall define the following macro as the maximum backlog queue 13071 length which may be specified by the backlog field of the listen( ) function: 13072 SOMAXCONN The maximum backlog queue length. 13073 The header shall define the following macros, with distinct integral values, for 13074 use as the valid values for the msg_flags field in the msghdr structure, or the flags parameter in 13075 recvfrom( ), recvmsg( ), sendmsg( ), or sendto( ) calls: 13076 MSG_CTRUNC Control data truncated. 13077 MSG_DONTROUTE Send without using routing tables. 13078 MSG_EOR Terminates a record (if supported by the protocol). 13079 MSG_OOB Out-of-band data. 13080 MSG_PEEK Leave received data in queue. 13081 MSG_TRUNC Normal data truncated. 13082 MSG_WAITALL Wait for complete message. 13083 The header shall define the following macros, with distinct integral values: 13084 AF_UNIX UNIX domain sockets. 13085 AF_UNSPEC Unspecified . 13086 AF_INET Internet domain sockets for use with IPv4 addresses. 13087 IP6 AF_INET6 Internet domain sockets for use with IPv6 addresses. 13088 The header shall define the following macros, with distinct integral values: 13089 SHUT_RD Disables further receive operations. 13090 SHUT_WR Disables further send operations. Base Definitions, Issue 6 391 Headers 13091 SHUT_RDWR Disables further send and receive operations. 13092 The following are declared as functions, and may also be defined as macros. Function prototypes 13093 shall be provided for use with an ISO C standard compiler. 13094 int accept(int, struct sockaddr *restrict, socklen_t *restrict); 13095 int bind(int, const struct sockaddr *, socklen_t); 13096 int connect(int, const struct sockaddr *, socklen_t); 13097 int getpeername(int, struct sockaddr *restrict, socklen_t *); 13098 int getsockname(int, struct sockaddr *restrict, socklen_t *); 13099 int getsockopt(int, int, int, void *restrict, socklen_t *restrict); 13100 int listen(int, int); 13101 ssize_t recv(int, void *, size_t, int); 13102 ssize_t recvfrom(int, void *restrict, size_t, int, 13103 struct sockaddr *restrict, socklen_t *restrict); 13104 ssize_t recvmsg(int, struct msghdr *, int); 13105 ssize_t send(int, const void *, size_t, int); 13106 ssize_t sendmsg(int, const struct msghdr *, int); 13107 ssize_t sendto(int, const void *, size_t, int, const struct sockaddr *, 13108 socklen_t); 13109 int setsockopt(int, int, int, const void *, socklen_t); 13110 int shutdown(int, int); 13111 int socket(int, int, int); 13112 int socketpair(int, int, int, int); 13113 Inclusion of may also make visible all symbols from . 13114 APPLICATION USAGE 13115 To forestall portability problems, it is recommended that applications not use values larger than 13116 232 -1 for the socklen_t type. 13117 The sockaddr_storage structure solves the problem of declaring storage for automatic variables 13118 which is both large enough and aligned enough for storing the socket address data structure of 13119 any family. For example, code with a file descriptor and without the context of the address 13120 family can pass a pointer to a variable of this type, where a pointer to a socket address structure 13121 is expected in calls such as getpeername( ), and determine the address family by accessing the 13122 received content after the call. 13123 An example implementation design of such a data structure would be as follows: 13124 /* 13125 * Desired design of maximum size and alignment. 13126 */ 13127 #define _SS_MAXSIZE 128 13128 /* Implementation-defined maximum size. */ 13129 #define _SS_ALIGNSIZE (sizeof(int64_t)) 13130 /* Implementation-defined desired alignment. */ 13131 /* 13132 * Definitions used for sockaddr_storage structure paddings design. 13133 */ 13134 #define _SS_PAD1SIZE (_SS_ALIGNSIZE - sizeof(sa_family_t)) 13135 #define _SS_PAD2SIZE (_SS_MAXSIZE - (sizeof(sa_family_t)+ 13136 _SS_PAD1SIZE + _SS_ALIGNSIZE)) 13137 struct sockaddr_storage { 13138 sa_family_t ss_family; /* Address family. */ 392 Technical Standard (2000) (Draft July 28, 2000) Headers 13139 /* 13140 * Following fields are implementation-defined. */ 13141 */ 13142 char _ss_pad1[_SS_PAD1SIZE]; 13143 /* 6-byte pad; this is to make implementation-defined 13144 pad up to alignment field that follows explicit in 13145 the data structure. */ 13146 int64_t _ss_align; /* Field to force desired structure 13147 storage alignment. */ 13148 char _ss_pad2[_SS_PAD2SIZE]; 13149 /* 112-byte pad to achieve desired size, 13150 _SS_MAXSIZE value minus size of ss_family 13151 __ss_pad1, __ss_align fields is 112. */ 13152 }; 13153 The above example illustrates a data structure which aligns on a 64-bit boundary. An | 13154 implementation-defined field _ss_align along _ss_pad1 is used to force a 64-bit alignment which | 13155 covers proper alignment good enough for needs of sockaddr_in6 (IPv6), sockaddr_in (IPv4) 13156 address data structures. The size of padding fields _ss_pad1 depends on the chosen alignment 13157 boundary. The size of padding field _ss_pad2 depends on the value of overall size chosen for the 13158 total size of the structure. This size and alignment are represented in the above example by | 13159 implementation-defined (not required) constants _SS_MAXSIZE (chosen value 128) and | 13160 _SS_ALIGNMENT (with chosen value 8). Constants _SS_PAD1SIZE (derived value 6) and 13161 _SS_PAD2SIZE (derived value 112) are also for illustration and not required. The | 13162 implementation-defined definitions and structure field names above start with an underscore to | 13163 denote implementation private name space. Portable code is not expected to access or reference 13164 those fields or constants. 13165 RATIONALE 13166 None. 13167 FUTURE DIRECTIONS 13168 None. 13169 SEE ALSO 13170 , the System Interfaces volume of IEEE Std. 1003.1-200x, accept( ), bind( ), connect( ), 13171 getpeername( ), getsockname( ), getsockopt( ), listen( ), recv( ), recvfrom( ), recvmsg( ), send( ), 13172 sendmsg( ), sendto( ), setsockopt( ), shutdown( ), socket( ), socketpair( ) 13173 CHANGE HISTORY 13174 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. | 13175 The restrict keyword is added to the prototypes for accept( ), getpeername( ), getsockname( ), | 13176 getsockopt( ), and recvfrom( ). | Base Definitions, Issue 6 393 Headers 13177 NAME 13178 sys/stat.h - data returned by the stat( ) function 13179 SYNOPSIS 13180 #include 13181 DESCRIPTION 13182 XSI The header shall define the structure of the data returned by the functions fstat( ), 13183 lstat( ),and stat( ). 13184 The stat structure shall contain at least the following members: 13185 dev_t st_dev ID of device containing file. 13186 ino_t st_ino File serial number. 13187 mode_t st_mode Mode of file (see below). 13188 nlink_t st_nlink Number of hard links to the file. 13189 uid_t st_uid User ID of file. 13190 gid_t st_gid Group ID of file. 13191 XSI dev_t st_rdev Device ID (if file is character or block special). 13192 off_t st_size For regular files, the file size in bytes. 13193 For symbolic links, the length in bytes of the 13194 path name contained in the symbolic link. 13195 For other file types, the use of this field is 13196 unspecified 13197 time_t st_atime Time of last access. 13198 time_t st_mtime Time of last data modification. 13199 time_t st_ctime Time of last status change. 13200 XSI blksize_t st_blksize A file system-specific preferred I/O block size for 13201 this object. In some file system types, this may 13202 vary from file to file. 13203 blkcnt_t st_blocks Number of blocks allocated for this object. 13204 13205 File serial number and device ID taken together uniquely identify the file within the system. The | 13206 blkcnt_t, blksize_t, dev_t, ino_t, mode_t, nlink_t, uid_t, gid_t, off_t, and time_t types shall be 13207 defined as described in . Times shall be given in seconds since the Epoch. | 13208 Unless otherwise specified, the structure members st_mode, st_ino, st_dev, st_uid, st_gid, st_atime, 13209 st_ctime, and st_mtime shall have meaningful values for all file types defined in 13210 IEEE Std. 1003.1-200x. 13211 For symbolic links, the st_mode member shall contain meaningful information, which can be 13212 used with the file type macros described below, that take a mode argument. The st_size member 13213 shall contain the length, in bytes, of the path name contained in the symbolic link. File mode bits 13214 and the contents of the remaining members of the stat structure are unspecified. The value 13215 returned in the st_size field shall be the length of the contents of the symbolic link, and shall not 13216 count a trailing null if one is present. 13217 The following symbolic names for the values of type mode_t shall also be defined. | 13218 File type: 13219 XSI S_IFMT Type of file. 13220 S_IFBLK Block special. 13221 S_IFCHR Character special. 394 Technical Standard (2000) (Draft July 28, 2000) Headers 13222 S_IFIFO FIFO special. 13223 S_IFREG Regular. 13224 S_IFDIR Directory. 13225 S_IFLNK Symbolic link. 13226 S_IFSOCK Socket. 13227 File mode bits: 13228 S_IRWXU Read, write, execute/search by owner. 13229 S_IRUSR Read permission, owner. 13230 S_IWUSR Write permission, owner. 13231 S_IXUSR Execute/search permission, owner. 13232 S_IRWXG Read, write, execute/search by group. 13233 S_IRGRP Read permission, group. 13234 S_IWGRP Write permission, group. 13235 S_IXGRP Execute/search permission, group. 13236 S_IRWXO Read, write, execute/search by others. 13237 S_IROTH Read permission, others. 13238 S_IWOTH Write permission, others. 13239 S_IXOTH Execute/search permission, others. 13240 S_ISUID Set-user-ID on execution. 13241 S_ISGID Set-group-ID on execution. 13242 XSI S_ISVTX On directories, restricted deletion flag. 13243 The bits defined by S_IRUSR, S_IWUSR, S_IXUSR, S_IRGRP, S_IWGRP, S_IXGRP, S_IROTH, 13244 XSI S_IWOTH, S_IXOTH, S_ISUID, S_ISGID, and S_ISVTXshall be unique. 13245 S_IRWXU is the bitwise-inclusive OR of S_IRUSR, S_IWUSR, and S_IXUSR. 13246 S_IRWXG is the bitwise-inclusive OR of S_IRGRP, S_IWGRP, and S_IXGRP. 13247 S_IRWXO is the bitwise-inclusive OR of S_IROTH, S_IWOTH, and S_IXOTH. 13248 Implementations may OR other implementation-defined bits into S_IRWXU, S_IRWXG, and | 13249 S_IRWXO, but they shall not overlap any of the other bits defined in this volume of 13250 IEEE Std. 1003.1-200x. The file permission bits are defined to be those corresponding to the 13251 bitwise-inclusive OR of S_IRWXU, S_IRWXG, and S_IRWXO. 13252 The following macros shall be provided to test whether a file is of the specified type. The value 13253 m supplied to the macros is the value of st_mode from a stat structure. The macro shall evaluate 13254 to a non-zero value if the test is true; 0 if the test is false. 13255 S_ISBLK(m) Test for a block special file. 13256 S_ISCHR(m) Test for a character special file. 13257 S_ISDIR(m) Test for a directory. Base Definitions, Issue 6 395 Headers 13258 S_ISFIFO(m) Test for a pipe or FIFO special file. 13259 S_ISREG(m) Test for a regular file. | 13260 S_ISLNK(m) Test for a symbolic link. | 13261 S_ISSOCK(m) Test for a socket. 13262 The implementation may implement message queues, semaphores, or shared memory objects as 13263 distinct file types. The following macros shall be provided to test whether a file is of the 13264 specified type. The value of the buf argument supplied to the macros is a pointer to a stat 13265 structure. The macro shall evaluate to a non-zero value if the specified object is implemented as 13266 a distinct file type and the specified file type is contained in the stat structure referenced by buf. 13267 Otherwise, the macro shall evaluate to zero. 13268 S_TYPEISMQ(buf) Test for a message queue. 13269 S_TYPEISSEM(buf) Test for a semaphore. 13270 S_TYPEISSHM(buf) Test for a shared memory object. 13271 TYM The implementation may implement typed memory objects as distinct file types, and the | 13272 following macro shall test whether a file is of the specified type. The value of the buf argument | 13273 supplied to the macros is a pointer to a stat structure. The macro shall evaluate to a non-zero 13274 value if the specified object is implemented as a distinct file type and the specified file type is 13275 contained in the stat structure referenced by buf. Otherwise, the macro shall evaluate to zero. 13276 S_TYPEISTMO(buf) Test macro for a typed memory object. 13277 13278 The following shall be declared as functions and may also be defined as macros. Function 13279 prototypes shall be provided for use with an ISO C standard compiler. 13280 int chmod(const char *, mode_t); 13281 int fchmod(int, mode_t); 13282 int fstat(int, struct stat *); 13283 int isfdtype(int, int); 13284 int lstat(const char *restrict, struct stat *restrict); 13285 int mkdir(const char *, mode_t); 13286 int mkfifo(const char *, mode_t); 13287 XSI int mknod(const char *, mode_t, dev_t); 13288 int stat(const char *restrict, struct stat *restrict); 13289 mode_t umask(mode_t); 13290 APPLICATION USAGE 13291 Use of the macros is recommended for determining the type of a file. 13292 RATIONALE 13293 A conforming C-language application must include for functions that have 13294 arguments or return values of type mode_t, so that symbolic values for that type can be used. 13295 An alternative would be to require that these constants are also defined by including 13296 . 13297 The S_ISUID and S_ISGID bits may be cleared on any write, not just on open( ), as some historical 13298 implementations do it. 13299 System calls that update the time entry fields in the stat structure must be documented by the 13300 implementors. POSIX-conforming systems should not update the time entry fields for functions 13301 listed in the System Interfaces volume of IEEE Std. 1003.1-200x unless the standard requires that 13302 they do, except in the case of documented extensions to the standard. 396 Technical Standard (2000) (Draft July 28, 2000) Headers 13303 Note that st_dev must be unique within a Local Area Network (LAN) in a ``system'' made up of 13304 multiple computers' file systems connected by a LAN. 13305 Networked implementations of a POSIX-conforming system must guarantee that all files visible 13306 within the file tree (including parts of the tree that may be remotely mounted from other 13307 machines on the network) on each individual processor are uniquely identified by the 13308 combination of the st_ino and st_dev fields. 13309 FUTURE DIRECTIONS 13310 None. 13311 SEE ALSO 13312 , the System Interfaces volume of IEEE Std. 1003.1-200x, chmod( ), fchmod( ), fstat( ), 13313 lstat( ), mkdir( ), mkfifo( ), mknod( ), stat( ), umask( ) 13314 CHANGE HISTORY 13315 First released in Issue 1. Derived from Issue 1 of the SVID. | 13316 Issue 4 13317 Reference to the header is added for the definitions of dev_t, ino_t, mode_t, 13318 nlink_t, uid_t, gid_t, off_t, and time_t. This has been marked as an extension. 13319 References to the S_IREAD, S_IWRITE, S_IEXEC file, and S_ISVTX modes are removed. 13320 The descriptions of the members of the stat structure in the DESCRIPTION are corrected. 13321 The following changes are incorporated for alignment with the ISO POSIX-1 standard: 13322 * The function declarations in this header are expanded to full ISO C standard prototypes. 13323 * The DESCRIPTION is expanded to include: 13324 - How files are uniquely identified within the system 13325 - Times are given in units of seconds since the Epoch 13326 - Rules governing the definition and use of the file mode bits 13327 - Usage of the file type test macros 13328 Issue 4, Version 2 13329 The following changes are incorporated for X/OPEN UNIX conformance: 13330 * The st_blksize and st_blocks members are added to the stat structure. 13331 * The S_IFLINK value of S_IFMT is defined. 13332 * The S_ISVTX file mode bit and the S_ISLNK file type test macro is defined. 13333 * The fchmod( ), lstat( ), and mknod( ) functions are added to the list of functions declared in this 13334 header. 13335 Issue 5 13336 The DESCRIPTION is updated for alignment with POSIX Realtime Extension. 13337 The type of st_blksize is changed from long to blksize_t; the type of st_blocks is changed from 13338 long to blkcnt_t. 13339 Issue 6 13340 The S_TYPEISMQ( ), S_TYPEISSEM( ), and S_TYPEISSHM( ) macros are unconditionally 13341 mandated. 13342 The Open Group corrigenda item U035/4 has been applied. In the DESCRIPTION, the types 13343 blksize_t and blkcnt_t have been described. Base Definitions, Issue 6 397 Headers 13344 The following new requirements on POSIX implementations derive from alignment with the 13345 Single UNIX Specification: 13346 * The dev_t, ino_t, mode_t, nlink_t, uid_t, gid_t, off_t, and time_t types are mandated. 13347 The isfdtype( ) function, S_IFSOCK, and S_ISSOCK are added for sockets. 13348 The description of stat structure members is changed to reflect contents when file type is a 13349 symbolic link. 13350 The test macro S_TYPEISTMO is added for alignment with IEEE Std. 1003.1j-2000. | 13351 The restrict keyword is added to the prototypes for lstat( ) and stat( ). | 398 Technical Standard (2000) (Draft July 28, 2000) Headers 13352 NAME 13353 sys/statvfs.h - VFS File System information structure 13354 SYNOPSIS 13355 XSI #include 13356 13357 DESCRIPTION 13358 The header shall define the statvfs structure that includes at least the following 13359 members: 13360 unsigned long f_bsize File system block size. 13361 unsigned long f_frsize Fundamental file system block size. 13362 fsblkcnt_t f_blocks Total number of blocks on file system in units of f_frsize. 13363 fsblkcnt_t f_bfree Total number of free blocks. 13364 fsblkcnt_t f_bavail Number of free blocks available to 13365 non-privileged process. 13366 fsfilcnt_t f_files Total number of file serial numbers. 13367 fsfilcnt_t f_ffree Total number of free file serial numbers. 13368 fsfilcnt_t f_favail Number of file serial numbers available to 13369 non-privileged process. 13370 unsigned long f_fsid File system ID. 13371 unsigned long f_flag Bit mask of f_flag values. 13372 unsigned long f_namemax Maximum file name length. 13373 The fsblkcnt_t and fsfilcnt_t types shall be defined as described in . 13374 The following flags for the f_flag member shall be defined: 13375 ST_RDONLY Read-only file system. 13376 ST_NOSUID Does not support setuid/setgid semantics. 13377 The header shall declare the following functions which may also be defined as 13378 macros. Function prototypes shall be provided for use with an ISO C standard compiler. 13379 int statvfs(const char *restrict, struct statvfs *restrict); 13380 int fstatvfs(int, struct statvfs *); 13381 APPLICATION USAGE 13382 None. 13383 RATIONALE 13384 None. 13385 FUTURE DIRECTIONS 13386 None. 13387 SEE ALSO 13388 , the System Interfaces volume of IEEE Std. 1003.1-200x, fstatvfs( ), statvfs( ) 13389 CHANGE HISTORY 13390 First released in Issue 4, Version 2. 13391 Issue 5 13392 The type of f_blocks, f_bfree, and f_bavail is changed from unsigned long to fsblkcnt_t; the type 13393 of f_files, f_ffree, and f_favail is changed from unsigned long to fsfilcnt_t. Base Definitions, Issue 6 399 Headers 13394 Issue 6 13395 The Open Group corrigenda item U035/5 has been applied. In the DESCRIPTION, the types 13396 fsblkcnt_t and fsfilcnt_t have been described. | 13397 The restrict keyword is added to the prototype for statvfs( ). | 400 Technical Standard (2000) (Draft July 28, 2000) Headers 13398 NAME 13399 sys/time.h - time types 13400 SYNOPSIS 13401 XSI #include 13402 13403 DESCRIPTION 13404 The header shall define the timeval structure that includes at least the following 13405 members: 13406 time_t tv_sec Seconds. 13407 suseconds_t tv_usec Microseconds. 13408 The header shall define the itimerval structure that includes at least the following 13409 members: 13410 struct timeval it_interval Timer interval. 13411 struct timeval it_value Current value. 13412 The time_t and suseconds_t types shall be defined as described in . 13413 The header shall define the fd_set type as a structure that includes at least the 13414 following member: 13415 long fds_bits[] Bit mask for open file descriptions. 13416 The header shall define the following values for the which argument of getitimer( ) 13417 and setitimer( ): 13418 ITIMER_REAL Decrements in real time. 13419 ITIMER_VIRTUAL Decrements in process virtual time. 13420 ITIMER_PROF Decrements both in process virtual time and when the system is running 13421 on behalf of the process. 13422 Each of the following may be declared as a function, or defined as a macro, or both: 13423 void FD_CLR(int fd, fd_set *fdset) 13424 Clears the bit for the file descriptor fd in the file descriptor set fdset. 13425 int FD_ISSET(int fd, fd_set *fdset) 13426 Returns a non-zero value if the bit for the file descriptor fd is set in the file descriptor set by 13427 fdset, and 0 otherwise. 13428 void FD_SET(int fd, fd_set *fdset) 13429 Sets the bit for the file descriptor fd in the file descriptor set fdset. 13430 void FD_ZERO(fd_set *fdset) 13431 Initializes the file descriptor set fdset to have zero bits for all file descriptors. | 13432 FD_SETSIZE | 13433 Maximum number of file descriptors in an fd_set structure. 13434 If implemented as macros, these may evaluate their arguments more than once, so that 13435 arguments must never be expressions with side effects. 13436 The following shall be declared as functions and may also be defined as macros. Function 13437 prototypes shall be provided for use with an ISO C standard compiler. 13438 int getitimer(int, struct itimerval *); 13439 int gettimeofday(struct timeval *, void *); Base Definitions, Issue 6 401 Headers 13440 int select(int, fd_set *restrict, fd_set *restrict, fd_set *restrict, 13441 struct timeval *restrict); 13442 int setitimer(int, const struct itimerval *restrict, 13443 struct itimerval *restrict); 13444 int utimes(const char *, const struct timeval [2]); (LEGACY) 13445 Inclusion of the header may make visible all symbols from the | 13446 header. | 13447 APPLICATION USAGE 13448 None. 13449 RATIONALE 13450 None. 13451 FUTURE DIRECTIONS 13452 None. 13453 SEE ALSO 13454 , the System Interfaces volume of IEEE Std. 1003.1-200x, getitimer( ), gettimeofday( ), 13455 select( ), setitimer( ) | 13456 CHANGE HISTORY 13457 First released in Issue 4, Version 2. 13458 Issue 5 13459 The type of tv_usec is changed from long to suseconds_t. | 13460 Issue 6 | 13461 The restrict keyword is added to the prototypes for select( ) and setitimer( ). | 13462 The note is added that inclusion of this header may also make symbols visible from | 13463 . | 402 Technical Standard (2000) (Draft July 28, 2000) Headers 13464 NAME 13465 sys/timeb.h - additional definitions for date and time 13466 SYNOPSIS 13467 XSI #include 13468 13469 DESCRIPTION 13470 The header shall define the timeb structure that includes at least the following 13471 members: 13472 time_t time The seconds portion of the current time. 13473 unsigned short millitm The milliseconds portion of the current time. 13474 short timezone The local timezone in minutes west of Greenwich. 13475 short dstflag TRUE if Daylight Savings Time is in effect. 13476 The time_t type shall be defined as described in . 13477 The header shall declare the following as a function which may also be defined as 13478 a macro. Function prototypes shall be provided for use with an ISO C standard compiler. 13479 int ftime(struct timeb *); (LEGACY) 13480 APPLICATION USAGE 13481 None. 13482 RATIONALE 13483 None. 13484 FUTURE DIRECTIONS 13485 None. 13486 SEE ALSO 13487 , | 13488 CHANGE HISTORY 13489 First released in Issue 4, Version 2. | 13490 Issue 6 | 13491 The ftime( ) function is marked LEGACY. | Base Definitions, Issue 6 403 Headers 13492 NAME 13493 sys/times.h - file access and modification times structure 13494 SYNOPSIS 13495 #include 13496 DESCRIPTION 13497 The header shall define the structure tms, which is returned by times( ) and 13498 includes at least the following members: 13499 clock_t tms_utime User CPU time. 13500 clock_t tms_stime System CPU time. 13501 clock_t tms_cutime User CPU time of terminated child processes. 13502 clock_t tms_cstime System CPU time of terminated child processes. 13503 The clock_t type shall be defined as described in . 13504 The following shall be declared as a function and may also be defined as a macro. Function 13505 prototypes shall be provided for use with an ISO C standard compiler. 13506 clock_t times(struct tms *); 13507 APPLICATION USAGE 13508 None. 13509 RATIONALE 13510 None. 13511 FUTURE DIRECTIONS 13512 None. 13513 SEE ALSO 13514 , the System Interfaces volume of IEEE Std. 1003.1-200x, times( ) 13515 CHANGE HISTORY 13516 First released in Issue 1. Derived from Issue 1 of the SVID. | 13517 Issue 4 13518 Reference to the header is added for the definitions of clock_t. 13519 This issue states that the times( ) function can also be defined as a macro. 13520 The following change is incorporated for alignment with the ISO POSIX-1 standard: 13521 * The function declarations in this header are expanded to full ISO C standard prototypes. 404 Technical Standard (2000) (Draft July 28, 2000) Headers 13522 NAME 13523 sys/types.h - data types 13524 SYNOPSIS 13525 #include 13526 DESCRIPTION 13527 The header shall include definitions for at least the following types: 13528 blkcnt_t Used for file block counts. 13529 blksize_t Used for block sizes. 13530 XSI clock_t Used for system times in clock ticks or CLOCKS_PER_SEC; see 13531 . 13532 TMR clockid_t Used for clock ID type in the clock and timer functions. 13533 dev_t Used for device IDs. 13534 XSI fsblkcnt_t Used for file system block counts. 13535 XSI fsfilcnt_t Used for file system file counts. 13536 gid_t Used for group IDs. 13537 XSI id_t Used as a general identifier; can be used to contain at least a pid_t, 13538 uid_t, or gid_t. 13539 ino_t Used for file serial numbers. 13540 XSI key_t Used for XSI interprocess communication. 13541 mode_t Used for some file attributes. 13542 nlink_t Used for link counts. 13543 off_t Used for file sizes. 13544 pid_t Used for process IDs and process group IDs. | 13545 THR pthread_attr_t Used to identify a thread attribute object. | 13546 BAR pthread_barrier_t Used to identify a barrier. 13547 BAR pthread_barrierattr_t Used to define a barrier attributes object. | 13548 THR pthread_cond_t Used for condition variables. | 13549 THR pthread_condattr_t Used to identify a condition attribute object. | 13550 THR pthread_key_t Used for thread-specific data keys. | 13551 THR pthread_mutex_t Used for mutexes. | 13552 THR pthread_mutexattr_t Used to identify a mutex attribute object. | 13553 THR pthread_once_t Used for dynamic package initialization. | 13554 THR pthread_rwlock_t Used for read-write locks. | 13555 THR pthread_rwlockattr_t Used for read-write lock attributes. | 13556 SPI pthread_spinlock_t Used to identify a spin lock. | 13557 THR pthread_t Used to identify a thread. | Base Definitions, Issue 6 405 Headers 13558 size_t Used for sizes of objects. 13559 ssize_t Used for a count of bytes or an error indication. 13560 XSI suseconds_t Used for time in microseconds 13561 time_t Used for time in seconds. 13562 TMR timer_t Used for timer ID returned by timer_create( ). 13563 uid_t Used for user IDs. 13564 XSI useconds_t Used for time in microseconds. 13565 All of the types shall be defined as arithmetic types of an appropriate length, with the following 13566 exceptions: 13567 XSI key_t 13568 THR pthread_attr_t | 13569 BAR pthread_barrier_t 13570 pthread_barrierattr_t 13571 THR pthread_cond_t | 13572 pthread_condattr_t 13573 pthread_key_t 13574 pthread_mutex_t 13575 pthread_mutexattr_t 13576 pthread_once_t 13577 pthread_rwlock_t | 13578 pthread_rwlockattr_t 13579 SPI pthread_spinlock_t 13580 TRC trace_attr_t | 13581 trace_event_id_t | 13582 TRC TEF trace_event_set_t | 13583 TRC trace_id_t | 13584 | 13585 Additionally: 13586 * blkcnt_t and off_t shall be signed integer types. | 13587 XSI * fsblkcnt_t, fsfilcnt_t, andino_t shall be defined as unsigned integer types. | 13588 * size_t shall be an unsigned integer type. | 13589 * blksize_t, pid_t, and ssize_t shall be signed integer types. | 13590 XSI The type ssize_t shall be capable of storing values at least in the range [-1, {SSIZE_MAX}]. The 13591 type useconds_t shall be an unsigned integer type capable of storing values at least in the range | 13592 [0, 1 000 000]. The type suseconds_t shall be a signed integer type capable of storing values at | 13593 least in the range [-1, 1 000 000]. | 13594 There are no defined comparison or assignment operators for the following types: 13595 THR pthread_attr_t | 13596 BAR pthread_barrier_t 13597 pthread_barrierattr_t 13598 THR pthread_cond_t | 13599 pthread_condattr_t 13600 pthread_mutex_t 13601 pthread_mutexattr_t 406 Technical Standard (2000) (Draft July 28, 2000) Headers 13602 pthread_rwlock_t | 13603 pthread_rwlockattr_t 13604 SPI pthread_spinlock_t 13605 TRC trace_attr_t | 13606 | 13607 APPLICATION USAGE 13608 None. 13609 RATIONALE 13610 None. 13611 FUTURE DIRECTIONS 13612 None. 13613 SEE ALSO 13614 13615 CHANGE HISTORY 13616 First released in Issue 1. Derived from Issue 1 of the SVID. | 13617 Issue 4 13618 The clock_t type is marked as an extension. 13619 In the last paragraph of the DESCRIPTION, only the reference to type key_t is now marked as 13620 an extension. 13621 The following changes are incorporated for alignment with the ISO POSIX-1 standard: 13622 * The data type ssize_t is added. 13623 * The DESCRIPTION is expanded to indicate the required arithmetic types. 13624 Issue 4, Version 2 13625 The id_t and useconds_t types are defined for X/OPEN UNIX conformance. The capability of 13626 the useconds_t type is described. 13627 Issue 5 13628 The clockid_t and timer_t types are defined for alignment with the POSIX Realtime Extension. 13629 The types blkcnt_t, blksize_t, fsblkcnt_t, fsfilcnt_t, and suseconds_t are added. 13630 Large File System extensions are added. 13631 Updated for alignment with the POSIX Threads Extension. 13632 Issue 6 13633 The pthread_barrier_t, pthread_barrierattr_t, and pthread_spinlock_t types are added for 13634 alignment with IEEE Std. 1003.1j-2000. 13635 The margin code is changed from XSI to THR for the pthread_rwlock_t and | 13636 pthread_rwlockattr_t types as Read-Write Locks have been absorbed into the POSIX Threads | 13637 option. The threads types are now marked THR. | Base Definitions, Issue 6 407 Headers 13638 NAME 13639 sys/uio.h - definitions for vector I/O operations 13640 SYNOPSIS 13641 XSI #include 13642 13643 DESCRIPTION 13644 The header shall define the iovec structure that includes at least the following 13645 members: 13646 void *iov_base Base address of a memory region for input or output. 13647 size_t iov_len The size of the memory pointed to by iov_base. 13648 The header uses the iovec structure for scatter/gather I/O. 13649 The ssize_t and size_t types shall be defined as described in . | 13650 The following shall be declared as functions and may also be defined as macros. Function | 13651 prototypes shall be provided for use with an ISO C standard compiler. 13652 ssize_t readv(int, const struct iovec *, int); 13653 ssize_t writev(int, const struct iovec *, int); 13654 APPLICATION USAGE 13655 The implementation can put a limit on the number of scatter/gather elements which can be | 13656 processed in one call. The symbol {IOV_MAX} defined in should always be used to | 13657 learn about the limits instead of assuming a fixed value. | 13658 RATIONALE 13659 Traditionally, the maximum number of scatter/gather elements the system can process in one | 13660 call were descibed by the symbolic value {UIO_MAXIOV}. In IEEE Std. 1003.1-200x this value | 13661 was replaced by the constant {IOV_MAX} which can be found in . | 13662 FUTURE DIRECTIONS 13663 None. 13664 SEE ALSO 13665 , , the System Interfaces volume of IEEE Std. 1003.1-200x, read( ), write( ) | 13666 CHANGE HISTORY 13667 First released in Issue 4, Version 2. 13668 Issue 6 13669 Text referring to scatter/gather I/O is added to the DESCRIPTION. 408 Technical Standard (2000) (Draft July 28, 2000) Headers 13670 NAME 13671 sys/un.h - definitions for UNIX domain sockets 13672 SYNOPSIS 13673 #include 13674 DESCRIPTION 13675 The header shall define the sockaddr_un structure that includes at least the 13676 following members: 13677 sa_family_t sun_family Address family. 13678 char sun_path[] Socket path name. 13679 The sockaddr_un structure is used to store addresses for UNIX domain sockets. Values of this 13680 type shall be cast by applications to struct sockaddr for use with socket functions. 13681 The sa_family_t type shall be defined as described in . 13682 APPLICATION USAGE 13683 The size of sun_path has intentionally been left undefined. This is because different 13684 implementations use different sizes. For example, BSD4.3 uses a size of 108, and BSD4.4 uses a 13685 size of 104. Since most implementations originate from BSD versions, the size is typically in the 13686 range 92 to 108. 13687 Applications should not assume a particular length for sun_path or assume that it can hold 13688 _POSIX_PATH_MAX characters (255). 13689 RATIONALE 13690 None. 13691 FUTURE DIRECTIONS 13692 None. 13693 SEE ALSO 13694 , the System Interfaces volume of IEEE Std. 1003.1-200x, bind( ), socket( ), 13695 socketpair( ) 13696 CHANGE HISTORY 13697 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. | Base Definitions, Issue 6 409 Headers 13698 NAME 13699 sys/utsname.h - system name structure 13700 SYNOPSIS 13701 #include 13702 DESCRIPTION 13703 The header shall define the structure utsname which shall include at least the 13704 following members: 13705 char sysname[] Name of this implementation of the operating system. 13706 char nodename[] Name of this node within an implementation-defined 13707 communications network. 13708 char release[] Current release level of this implementation. 13709 char version[] Current version level of this release. 13710 char machine[] Name of the hardware type on which the system is running. 13711 The character arrays are of unspecified size, but the data stored in them shall be terminated by a 13712 null byte. 13713 The following shall be declared as a function and may also be defined as a macro: 13714 int uname(struct utsname *); 13715 APPLICATION USAGE 13716 None. 13717 RATIONALE 13718 None. 13719 FUTURE DIRECTIONS 13720 None. 13721 SEE ALSO 13722 The System Interfaces volume of IEEE Std. 1003.1-200x, uname( ) 13723 CHANGE HISTORY 13724 First released in Issue 1. Derived from Issue 1 of the SVID. | 13725 Issue 4 13726 The word ``character'' is replaced with the word ``byte'' in the DESCRIPTION. 13727 The function in this header can now also be defined as a macro. 13728 The following change is incorporated for alignment with the ISO C standard: 13729 * The function declarations in this header are expanded to full ISO C standard prototypes. 410 Technical Standard (2000) (Draft July 28, 2000) Headers 13730 NAME 13731 sys/wait.h - declarations for waiting 13732 SYNOPSIS 13733 #include 13734 DESCRIPTION 13735 The header shall define the following symbolic constants for use with waitpid( ): 13736 WNOHANG Do not hang if no status is available; return immediately. 13737 WUNTRACED Report status of stopped child process. 13738 The header shall define the following macros for analysis of process status values: 13739 WEXITSTATUS Return exit status. 13740 XSI WIFCONTINUED True if child has been continued 13741 WIFEXITED True if child exited normally. 13742 WIFSIGNALED True if child exited due to uncaught signal. 13743 WIFSTOPPED True if child is currently stopped. 13744 WSTOPSIG Return signal number that caused process to stop. 13745 WTERMSIG Return signal number that caused process to terminate. 13746 XSI The following symbolic constants shall be defined as possible values for the options argument to 13747 waitid( ): 13748 WEXITED Wait for processes that have exited. 13749 WSTOPPED Status is returned for any child that has stopped upon receipt of a signal. 13750 WCONTINUED Status is returned for any child that was stopped and has been continued. 13751 WNOHANG Return immediately if there are no children to wait for. 13752 WNOWAIT Keep the process whose status is returned in infop in a waitable state. 13753 The type idtype_t shall be defined as an enumeration type whose possible values shall include 13754 at least the following: 13755 P_ALL 13756 P_PID 13757 P_PGID 13758 13759 The id_t and pid_t types shall be defined as described in . | 13760 XSI The siginfo_t type shall be defined as described in . 13761 The rusage structure shall be defined as described in . 13762 Inclusion of the header may also make visible all symbols from and 13763 . 13764 The following shall be declared as functions and may also be defined as macros. Function 13765 prototypes shall be provided for use with an ISO C standard compiler. 13766 pid_t wait(int *); 13767 XSI int waitid(idtype_t, id_t, siginfo_t *, int); 13768 pid_t waitpid(pid_t, int *, int); Base Definitions, Issue 6 411 Headers 13769 APPLICATION USAGE 13770 None. 13771 RATIONALE 13772 None. 13773 FUTURE DIRECTIONS 13774 None. 13775 SEE ALSO 13776 , , , , the System Interfaces volume of 13777 IEEE Std. 1003.1-200x, wait( ), waitid( ) 13778 CHANGE HISTORY 13779 First released in Issue 3. 13780 Entry included for alignment with the POSIX.1-1988 standard. 13781 Issue 4 13782 Reference to the header is added for the definition of pid_t and marked as an 13783 extension. 13784 The following change is incorporated for alignment with the ISO POSIX-1 standard: 13785 * The function declarations in this header are expanded to full ISO C standard prototypes. 13786 Issue 4, Version 2 13787 The following changes are incorporated for X/OPEN UNIX conformance: 13788 * The WIFCONTINUED macro, the list of symbolic constants for the options argument to 13789 waitid( ), and the description of the idtype_t enumeration type are added. 13790 * A statement is added indicated that inclusion of this header may also make visible constants 13791 from and . 13792 * The wait3( ) and waitid( ) functions are added to the list of functions declared in this header. 13793 Issue 6 | 13794 The wait3( ) function is removed. | 412 Technical Standard (2000) (Draft July 28, 2000) Headers 13795 NAME 13796 syslog - definitions for system error logging 13797 SYNOPSIS 13798 XSI #include 13799 13800 DESCRIPTION 13801 The header shall define the following symbolic constants, zero or more of which may 13802 be OR'ed together to form the logopt option of openlog( ): 13803 LOG_PID Log the process ID with each message. 13804 LOG_CONS Log to the system console on error. 13805 LOG_NDELAY Connect to syslog daemon immediately. 13806 LOG_ODELAY Delay open until syslog( ) is called. 13807 LOG_NOWAIT Do not wait for child processes. 13808 The following symbolic constants shall be defined as possible values of the facility argument to 13809 openlog( ): 13810 LOG_KERN Reserved for message generated by the system. 13811 LOG_USER Message generated by a process. 13812 LOG_MAIL Reserved for message generated by mail system. 13813 LOG_NEWS Reserved for message generated by news system. 13814 LOG_UUCP Reserved for message generated by UUCP system. 13815 LOG_DAEMON Reserved for message generated by system daemon. 13816 LOG_AUTH Reserved for message generated by authorization daemon. 13817 LOG_CRON Reserved for message generated by the clock daemon. 13818 LOG_LPR Reserved for message generated by printer system. 13819 LOG_LOCAL0 Reserved for local use. 13820 LOG_LOCAL1 Reserved for local use. 13821 LOG_LOCAL2 Reserved for local use. 13822 LOG_LOCAL3 Reserved for local use. 13823 LOG_LOCAL4 Reserved for local use. 13824 LOG_LOCAL5 Reserved for local use. 13825 LOG_LOCAL6 Reserved for local use. 13826 LOG_LOCAL7 Reserved for local use. 13827 The following shall be declared as macros for constructing the maskpri argument to setlogmask( ). 13828 The following macros expand to an expression of type int when the argument pri is an 13829 expression of type int: 13830 LOG_MASK(pri) A mask for priority pri. 13831 The following constants shall be defined as possible values for the priority argument of syslog( ): Base Definitions, Issue 6 413 Headers 13832 LOG_EMERG A panic condition was reported to all processes. 13833 LOG_ALERT A condition that should be corrected immediately. 13834 LOG_CRIT A critical condition. 13835 LOG_ERR An error message. 13836 LOG_WARNING A warning message. 13837 LOG_NOTICE A condition requiring special handling. 13838 LOG_INFO A general information message. 13839 LOG_DEBUG A message useful for debugging programs. 13840 The following shall be declared as functions and may also be defined as macros. Function 13841 prototypes shall be provided for use with an ISO C standard compiler. 13842 void closelog(void); 13843 void openlog(const char *, int, int); 13844 int setlogmask(int); 13845 void syslog(int, const char *, ...); 13846 APPLICATION USAGE 13847 None. 13848 RATIONALE 13849 None. 13850 FUTURE DIRECTIONS 13851 None. 13852 SEE ALSO 13853 The System Interfaces volume of IEEE Std. 1003.1-200x, closelog( ) 13854 CHANGE HISTORY 13855 First released in Issue 4, Version 2. 13856 Issue 5 13857 Moved to X/Open UNIX to BASE. 414 Technical Standard (2000) (Draft July 28, 2000) Headers 13858 NAME 13859 tar.h - extended tar definitions 13860 SYNOPSIS 13861 #include 13862 DESCRIPTION 13863 The header shall define header block definitions as follows. 13864 General definitions: 13865 ______________________________________________________________________________ 13866 Name Description Value ______________________________________________________________________________ 13867 TMAGIC "ustar" ustar plus null byte. 13868 TMAGLEN 6 Length of the above. 13869 TVERSION "00" 00 without a null byte. 13870 TVERSLEN 2 Length of the above. ______________________________________________________________________________ 13871 Typeflag field definitions: 13872 ______________________________________________________________________________ 13873 Name Description Value ______________________________________________________________________________ 13874 REGTYPE '0' Regular file. 13875 AREGTYPE '\0' Regular file. 13876 LNKTYPE '1' Link. 13877 SYMTYPE '2' Symbolic link. 13878 CHRTYPE '3' Character special. 13879 BLKTYPE '4' Block special. 13880 DIRTYPE '5' Directory. 13881 FIFOTYPE '6' FIFO special. 13882 CONTTYPE '7' Reserved. ______________________________________________________________________________ 13883 Mode field bit definitions (octal): 13884 ______________________________________________________________________________ 13885 Name Description Value ______________________________________________________________________________ 13886 TSUID 04000 Set UID on execution. 13887 TSGID 02000 Set GID on execution. 13888 XSI TSVTX 01000 On directories, restricted deletion flag. 13889 TUREAD 00400 Read by owner. 13890 TUWRITE 00200 Write by owner special. 13891 TUEXEC 00100 Execute/search by owner. 13892 TGREAD 00040 Read by group. 13893 TGWRITE 00020 Write by group. 13894 TGEXEC 00010 Execute/search by group. 13895 TOREAD 00004 Read by other. 13896 TOWRITE 00002 Write by other. 13897 TOEXEC 00001 Execute/search by other. ______________________________________________________________________________ Base Definitions, Issue 6 415 Headers 13898 APPLICATION USAGE 13899 None. 13900 RATIONALE 13901 None. 13902 FUTURE DIRECTIONS 13903 None. 13904 SEE ALSO 13905 The Shell and Utilities volume of IEEE Std. 1003.1-200x, pax | 13906 CHANGE HISTORY 13907 First released in Issue 3. Derived from the entry in the POSIX.1-1988 standard. | 13908 Issue 4 13909 This entry is moved from the Headers Interface, Issue 3 specification. | 13910 Issue 4, Version 2 13911 The following changes are incorporated for X/OPEN UNIX conformance: 13912 * The significance of SYMTYPE as the value of the typeflag field is explained. 13913 * The value of TSVTX as the value of the mode field is explained. 13914 Issue 6 13915 The SEE ALSO section now refers to pax since the Shell and Utilities volume of | 13916 IEEE Std. 1003.1-200x no longer contains the tar utility. | 416 Technical Standard (2000) (Draft July 28, 2000) Headers 13917 NAME 13918 termios.h - define values for termios 13919 SYNOPSIS 13920 #include 13921 DESCRIPTION 13922 The header contains the definitions used by the terminal I/O interfaces (see 13923 Chapter 11 (on page 213) for the structures and names defined). 13924 The termios Structure 13925 The following data types shall be defined through typedef: 13926 cc_t Used for terminal special characters. 13927 speed_t Used for terminal baud rates. 13928 tcflag_t Used for terminal modes. 13929 The above types shall be all unsigned integer types. | 13930 The termios structure shall be defined, and shall include at least the following members: 13931 tcflag_t c_iflag Input modes. 13932 tcflag_t c_oflag Output modes. 13933 tcflag_t c_cflag Control modes. 13934 tcflag_t c_lflag Local modes. 13935 cc_t c_cc[NCCS] Control characters. 13936 A definition shall be provided for: 13937 NCCS Size of the array c_cc for control characters. 13938 The following subscript names for the array c_cc shall be defined: 13939 __________________________________________________________ 13940 Subscript Usage 13941 _ Canonical Mode Non-Canonical Mode Description _________________________________________________________ 13942 VEOF EOF character. 13943 VEOL EOL character. 13944 VERASE ERASE character. 13945 VINTR VINTR INTR character. 13946 VKILL KILL character. 13947 VMIN MIN value. 13948 VQUIT VQUIT QUIT character. 13949 VSTART VSTART START character. 13950 VSTOP VSTOP STOP character. 13951 VSUSP VSUSP SUSP character. 13952 _ VTIME TIME value. _________________________________________________________ 13953 The subscript values shall be unique, except that the VMIN and VTIME subscripts may have the 13954 same values as the VEOF and VEOL subscripts, respectively. 13955 The following flags shall be provided. Base Definitions, Issue 6 417 Headers 13956 Input Modes 13957 The c_iflag field describes the basic terminal input control: 13958 BRKINT Signal interrupt on break. 13959 ICRNL Map CR to NL on input. 13960 IGNBRK Ignore break condition. 13961 IGNCR Ignore CR. 13962 IGNPAR Ignore characters with parity errors. 13963 INLCR Map NL to CR on input. 13964 INPCK Enable input parity check. 13965 ISTRIP Strip character. 13966 XSI IXANY Enable any character to restart output. 13967 IXOFF Enable start/stop input control. 13968 IXON Enable start/stop output control. 13969 PARMRK Mark parity errors. 13970 Output Modes 13971 The c_oflag field specifies the system treatment of output: 13972 OPOST Post-process output. 13973 XSI ONLCR Map NL to CR-NL on output. 13974 OCRNL Map CR to NL on output. 13975 ONOCR No CR output at column 0. 13976 ONLRET NL performs CR function. 13977 OFILL Use fill characters for delay. 13978 NLDLY Select newline delays: 13979 NL0 character type 0. 13980 NL1 character type 1. 13981 CRDLY Select carriage-return delays: 13982 CR0 Carriage-return delay type 0. 13983 CR1 Carriage-return delay type 1. 13984 CR2 Carriage-return delay type 2. 13985 CR3 Carriage-return delay type 3. 13986 TABDLY Select horizontal-tab delays: 13987 TAB0 Horizontal-tab delay type 0. 13988 TAB1 Horizontal-tab delay type 1. 13989 TAB2 Horizontal-tab delay type 2. 418 Technical Standard (2000) (Draft July 28, 2000) Headers 13990 TAB3 Expand tabs to spaces. 13991 BSDLY Select backspace delays: 13992 BS0 Backspace-delay type 0. 13993 BS1 Backspace-delay type 1. 13994 VTDLY Select vertical-tab delays: 13995 VT0 Vertical-tab delay type 0. 13996 VT1 Vertical-tab delay type 1. 13997 FFDLY Select form-feed delays: 13998 FF0 Form-feed delay type 0. 13999 FF1 Form-feed delay type 1. 14000 Baud Rate Selection 14001 The input and output baud rates are stored in the termios structure. These are the valid values 14002 for objects of type speed_t. The following values shall be defined, but not all baud rates need be 14003 supported by the underlying hardware. 14004 B0 Hang up 14005 B50 50 baud 14006 B75 75 baud 14007 B110 110 baud 14008 B134 134.5 baud 14009 B150 150 baud 14010 B200 200 baud 14011 B300 300 baud 14012 B600 600 baud 14013 B1200 1200 baud 14014 B1800 1800 baud 14015 B2400 2400 baud 14016 B4800 4800 baud 14017 B9600 9600 baud 14018 B19200 19200 baud 14019 B38400 38400 baud Base Definitions, Issue 6 419 Headers 14020 Control Modes 14021 The c_cflag field describes the hardware control of the terminal; not all values specified are 14022 required to be supported by the underlying hardware: 14023 CSIZE Character size: 14024 CS5 5 bits 14025 CS6 6 bits 14026 CS7 7 bits 14027 CS8 8 bits 14028 CSTOPB Send two stop bits, else one. 14029 CREAD Enable receiver. 14030 PARENB Parity enable. 14031 PARODD Odd parity, else even. 14032 HUPCL Hang up on last close. 14033 CLOCAL Ignore modem status lines. 14034 Local Modes 14035 The c_lflag field of the argument structure is used to control various terminal functions: 14036 ECHO Enable echo. 14037 ECHOE Echo erase character as error-correcting backspace. 14038 ECHOK Echo KILL. 14039 ECHONL Echo NL. 14040 ICANON Canonical input (erase and kill processing). 14041 IEXTEN Enable extended input character processing. 14042 ISIG Enable signals. 14043 NOFLSH Disable flush after interrupt or quit. 14044 TOSTOP Send SIGTTOU for background output. 14045 Attribute Selection 14046 The following symbolic constants for use with tcsetattr( ) are defined: 14047 TCSANOW Change attributes immediately. 14048 TCSADRAIN Change attributes when output has drained. 14049 TCSAFLUSH Change attributes when output has drained; also flush pending input. 420 Technical Standard (2000) (Draft July 28, 2000) Headers 14050 Line Control 14051 The following symbolic constants for use with tcflush( ) shall be defined: 14052 TCIFLUSH Flush pending input. Flush untransmitted output. 14053 TCIOFLUSH Flush both pending input and untransmitted output. 14054 TCOFLUSH Flush untransmitted output. 14055 The following symbolic constants for use with tcflow( ) shall be defined: 14056 TCIOFF Transmit a STOP character, intended to suspend input data. 14057 TCION Transmit a START character, intended to restart input data. 14058 TCOOFF Suspend output. 14059 TCOON Restart output. 14060 The following shall be declared as functions and may also be defined as macros. Function 14061 prototypes shall be provided for use with an ISO C standard compiler. 14062 speed_t cfgetispeed(const struct termios *); 14063 speed_t cfgetospeed(const struct termios *); 14064 int cfsetispeed(struct termios *, speed_t); 14065 int cfsetospeed(struct termios *, speed_t); 14066 int tcdrain(int); 14067 int tcflow(int, int); 14068 int tcflush(int, int); 14069 int tcgetattr(int, struct termios *); 14070 XSI pid_t tcgetsid(int); 14071 int tcsendbreak(int, int); 14072 int tcsetattr(int, int, struct termios *); 14073 APPLICATION USAGE 14074 The following names are commonly used as extensions to the above, therefore portable 14075 applications must not use them: | 14076 XSI CBAUD EXTB VDSUSP 14077 DEFECHO FLUSHO VLNEXT 14078 ECHOCTL LOBLK VREPRINT 14079 ECHOKE PENDIN VSTATUS 14080 ECHOPRT SWTCH VWERASE 14081 EXTA VDISCARD 14082 Note: These names are not used in IEEE Std. 1003.1-200x, but are reserved for historical use. | 14083 RATIONALE | 14084 None. 14085 FUTURE DIRECTIONS 14086 None. 14087 SEE ALSO 14088 The System Interfaces volume of IEEE Std. 1003.1-200x, cfgetispeed( ), cfgetospeed( ), cfsetispeed( ), 14089 cfsetospeed( ), tcdrain( ), tcflow( ), tcflush( ), tcgetattr( ), tcgetsid( ), tcsendbreak( ), tcsetattr( ), Chapter 14090 11 (on page 213) Base Definitions, Issue 6 421 Headers 14091 CHANGE HISTORY 14092 First released in Issue 3. 14093 Entry included for alignment with the ISO POSIX-1 standard. 14094 Issue 4 14095 The following words are removed from the description of the c_cc array: ``Implementations that 14096 do not support the job control option, may ignore the SUSP character value in the c_cc array 14097 indexed by the VSUSP subscript.'' This is because job control is defined as mandatory for Issue 4 14098 conforming implementations. 14099 The mask name symbols IUCLC and OLCUC are marked LEGACY. | 14100 The following changes are incorporated for alignment with the ISO POSIX-1 standard: 14101 * The function declarations in this header are expanded to full ISO C standard prototypes. 14102 * Some minor rewording of the DESCRIPTION is done to align the text more exactly with the 14103 ISO POSIX-1 standard. No functional differences are implied by these changes. 14104 * The list of mask name symbols for the c_oflag field have all been marked as extensions, with 14105 the exception of OPOST. 14106 Issue 4, Version 2 14107 For X/OPEN UNIX conformance, the tcgetsid( ) function is added to the list of functions declared 14108 in this header. 14109 Issue 6 | 14110 The LEGACY symbols IUCLC, ULCUC, and XCASE are removed. 422 Technical Standard (2000) (Draft July 28, 2000) Headers 14111 NAME | 14112 tgmath.h - type-generic macros | 14113 SYNOPSIS | 14114 #include | 14115 DESCRIPTION | 14116 CX The functionality described on this reference page extends the ISO C standard. Applications | 14117 shall define the appropriate feature test macro (see the System Interfaces volume of | 14118 IEEE Std. 1003.1-200x, Section 2.2, The Compilation Environment) to enable the visibility of | 14119 symbols in this header. | 14120 The header shall include the headers and and shall define | 14121 several type-generic macros. | 14122 Of the functions contained within the and headers without an f (float) or | 14123 l (long double) suffix, several have one or more parameters whose corresponding real type is | 14124 double. For each such function, except modf( ), there shall be a corresponding type-generic | 14125 macro. The parameters whose corresponding real type is double in the function synopsis are | 14126 generic parameters. Use of the macro invokes a function whose corresponding real type and | 14127 type domain are determined by the arguments for the generic parameters. | 14128 Use of the macro invokes a function whose generic parameters have the corresponding real type | 14129 determined as follows: | 14130 * First, if any argument for generic parameters has type long double, the type determined is | 14131 long double. | 14132 * Otherwise, if any argument for generic parameters has type double or is of integer type, the | 14133 type determined is double. | 14134 * Otherwise, the type determined is float. | 14135 For each unsuffixed function in the header for which there is a function in the | 14136 header with the same name except for a c prefix, the corresponding type-generic | 14137 macro (for both functions) has the same name as the function in the header. The | 14138 corresponding type-generic macro for fabs( ) and cabs( ) is fabs( ). | Base Definitions, Issue 6 423 Headers 14139 _________________________________________ | 14140 Type-Generic | 14141 _ Function Function Macro ________________________________________ || 14142 acos( ) cacos( ) acos( ) | 14143 asin( ) casin( ) asin( ) | 14144 atan( ) catan( ) atan( ) | 14145 acosh( ) cacosh( ) acosh( ) | 14146 asinh( ) casinh( ) asinh( ) | 14147 atanh( ) catanh( ) atanh( ) | 14148 cos( ) ccos( ) cos( ) | 14149 sin( ) csin( ) sin( ) | 14150 tan( ) ctan( ) tan( ) | 14151 cosh( ) ccosh( ) cosh( ) | 14152 sinh( ) csinh( ) sinh( ) | 14153 tanh( ) ctanh( ) tanh( ) | 14154 exp( ) cexp( ) exp( ) | 14155 log( ) clog( ) log( ) | 14156 pow() cpow() pow() | 14157 sqrt( ) csqrt( ) sqrt( ) | 14158 _ fabs( ) cabs( ) fabs( ) ________________________________________ |||||| 14159 If at least one argument for a generic parameter is complex, then use of the macro invokes a | 14160 complex function; otherwise, use of the macro invokes a real function. | 14161 For each unsuffixed function in the header without a c-prefixed counterpart in the | 14162 header, the corresponding type-generic macro has the same name as the function. | 14163 These type-generic macros are: | 14164 atan2( ) fma( ) llround( ) remainder( ) ||||| 14165 cbrt( ) fmax( ) log10( ) remquo( ) |||| 14166 ceil( ) fmin( ) log1p( ) rint( ) |||| 14167 copysign( ) fmod( ) log2( ) round( ) |||| 14168 erf( ) frexp( ) logb( ) scalbn( ) |||| 14169 erfc( ) hypot( ) lrint( ) scalbln( ) |||| 14170 exp2( ) ilogb( ) lround( ) tgamma( ) |||| 14171 expm1( ) ldexp( ) nearbyint( ) trunc( ) |||| 14172 fdim( ) lgamma( ) nextafter( ) ||| 14173 floor( ) llrint( ) nexttoward( ) ||| 14174 If all arguments for generic parameters are real, then use of the macro invokes a real function; | 14175 otherwise, use of the macro results in undefined behavior. | 14176 For each unsuffixed function in the header that is not a c-prefixed counterpart to a | 14177 function in the header, the corresponding type-generic macro has the same name as | 14178 the function. These type-generic macros are: | 14179 carg( ) | 14180 cimag( ) | 14181 conj( ) | 14182 cproj( ) | 14183 creal( ) | 14184 Use of the macro with any real or complex argument invokes a complex function. | 424 Technical Standard (2000) (Draft July 28, 2000) Headers 14185 APPLICATION USAGE | 14186 With the declarations: | 14187 #include | 14188 int n; | 14189 float f; | 14190 double d; | 14191 long double ld; | 14192 float complex fc; | 14193 double complex dc; | 14194 long double complex ldc; | 14195 functions invoked by use of type-generic macros are shown in the following table: | ___________________________________________ | 14196 _ Macro Use Invokes __________________________________________ || 14197 exp(n) exp(n), the function | 14198 acosh(f) acoshf(f) | 14199 sin(d) sin(d), the function | 14200 atan(ld) atanl(ld) | 14201 log(fc) clogf(fc) | 14202 sqrt(dc) csqrt(dc) | 14203 pow(ldc,f) cpowl(ldc, f) | 14204 remainder(n,n) remainder(n, n), the function | 14205 nextafter(d,f) nextafter(d, f), the function | 14206 nexttoward(f,ld) nexttowardf(f, ld) | 14207 copysign(n,ld) copysignl(n, ld) | 14208 ceil(fc) Undefined behavior | 14209 rint(dc) Undefined behavior | 14210 fmax(ldc,ld) Undefined behavior | 14211 carg(n) carg(n), the function | 14212 cproj(f) cprojf(f) | 14213 creal(d) creal(d), the function | 14214 cimag(ld) cimagl(ld) | 14215 cabs(fc) cabsf(fc) | 14216 carg(dc) carg(dc), the function | 14217 _ cproj(ldc) cprojl(ldc) __________________________________________ ||||| 14218 RATIONALE | 14219 Type-generic macros allow calling a function whose type is determined by the argument type, as | 14220 is the case for C operators such as '+' and '*'. For example, with a type-generic cos( ) macro, | 14221 the expression cos((float)x) will have type float. This feature enables writing more portably | 14222 efficient code and alleviates need for awkward casting and suffixing in the process of porting or | 14223 adjusting precision. Generic math functions are a widely appreciated feature of Fortran. | 14224 The only arguments that affect the type resolution are the arguments corresponding to the | 14225 parameters that have type double in the synopsis. Hence the type of a type-generic call to | 14226 nexttoward( ), whose second parameter is long double in the synopsis, is determined solely by | 14227 the type of the first argument. | 14228 The term ``type-generic'' was chosen over the proposed alternatives of intrinsic and overloading. | 14229 The term is more specific than intrinsic, which already is widely used with a more general | 14230 meaning, and reflects a closer match to Fortran's generic functions than to C++ overloading. | 14231 The macros are placed in their own header in order not to silently break old programs that | 14232 include the header; for example, with: | Base Definitions, Issue 6 425 Headers 14233 printf ("%e", sin(x)) | 14234 modf(double, double*) is excluded because no way was seen to make it safe without | 14235 complicating the type resolution. | 14236 The implementation might, as an extension, endow appropriate ones of the macros that | 14237 IEEE Std. 1003.1-200x specifies only for real arguments with the ability to invoke the complex | 14238 functions. | 14239 IEEE Std. 1003.1-200x does not prescribe any particular implementation mechanism for generic | 14240 macros. It could be implemented simply with built-in macros. The generic macro for sqrt( ), for | 14241 example, could be implemented with: | 14242 #undef sqrt | 14243 #define sqrt(x) __BUILTIN_GENERIC_sqrt(x) | 14244 Generic macros are designed for a useful level of consistency with C++ overloaded math | 14245 functions. | 14246 The great majority of existing C programs are expected to be unaffected when the | 14247 header is included instead of the or headers. Generic macros are similar | 14248 to the ISO/IEC 9899: 1999 standard library masking macros, though the semantic types of return | 14249 values differ. | 14250 The ability to overload on integer as well as floating types would have been useful for some | 14251 functions; for example, copysign( ). Overloading with different numbers of arguments would | 14252 have allowed reusing names; for example, remainder( ) for remquo( ). However, these facilities | 14253 would have complicated the specification; and their natural consistent use, such as for a floating | 14254 abs( ) or a two-argument atan( ), would have introduced further inconsistencies with the | 14255 ISO/IEC 9899: 1999 standard for insufficient benefit. | 14256 The ISO C standard in no way limits the implementation's options for efficiency, including | 14257 inlining library functions. | 14258 FUTURE DIRECTIONS | 14259 None. | 14260 SEE ALSO | 14261 , , the System Interfaces volume of IEEE Std. 1003.1-200x, cabs( ), fabs( ), | 14262 modf( ) | 14263 CHANGE HISTORY || 14264 First released in Issue 6. Included for alignment with the ISO/IEC 9899: 1999 standard. | 426 Technical Standard (2000) (Draft July 28, 2000) Headers 14265 NAME 14266 time.h - time types 14267 SYNOPSIS 14268 #include 14269 DESCRIPTION 14270 CX The functionality described on this reference page extends the ISO C standard. Applications 14271 shall define the appropriate feature test macro (see the System Interfaces volume of 14272 IEEE Std. 1003.1-200x, Section 2.2, The Compilation Environment) to enable the visibility of 14273 symbols in this header. 14274 The header shall declare the structure tm, which shall include at least the following 14275 members: 14276 int tm_sec Seconds [0,60]. 14277 int tm_min Minutes [0,59]. 14278 int tm_hour Hour [0,23]. 14279 int tm_mday Day of month [1,31]. 14280 int tm_mon Month of year [0,11]. 14281 int tm_year Years since 1900. 14282 int tm_wday Day of week [0,6] (Sunday =0). 14283 int tm_yday Day of year [0,365]. 14284 int tm_isdst Daylight savings flag. 14285 The value of tm_isdst shall be positive if Daylight Saving Time is in effect, 0 if Daylight Saving 14286 Time is not in effect, and negative if the information is not available. 14287 The header shall define the following symbolic names: 14288 NULL Null pointer constant. 14289 CLOCKS_PER_SEC A number used to convert the value returned by the clock( ) function into 14290 seconds. 14291 TMR|CPT CLOCK_PROCESS_CPUTIME_ID 14292 The identifier of the CPU-time clock associated with the process making a 14293 clock( ) or timer*( ) function call. 14294 TMR|TCT CLOCK_THREAD_CPUTIME_ID 14295 The identifier of the CPU-time clock associated with the thread making a 14296 clock( ) or timer*( ) function call. 14297 TMR The header shall declare the structure timespec, which has at least the following 14298 members: 14299 time_t tv_sec Seconds. 14300 long tv_nsec Nanoseconds. 14301 The header shall also declare the itimerspec structure, which has at least the following 14302 members: 14303 struct timespec it_interval Timer period. 14304 struct timespec it_value Timer expiration. 14305 The following manifest constants shall be defined: 14306 CLOCK_REALTIME The identifier of the system-wide realtime clock. 14307 TIMER_ABSTIME Flag indicating time is absolute with respect to the clock associated with a 14308 timer. Base Definitions, Issue 6 427 Headers 14309 MON CLOCK_MONOTONIC 14310 The identifier for the system-wide monotonic clock, which is defined as a 14311 clock whose value cannot be set via clock_settime( ) and which cannot 14312 have backward clock jumps. The maximum possible clock jump shall be | 14313 implementation-defined. | 14314 TMR The clock_t, size_t, time_t, clockid_t, and timer_t types shall be defined as described in 14315 . 14316 XSI Although the value of CLOCKS_PER_SEC is required to be 1 million on all XSI-conformant 14317 systems, it may be variable on other systems, and it should not be assumed that 14318 CLOCKS_PER_SEC is a compile-time constant. 14319 XSI The header shall provide a declaration for getdate_err. 14320 The following shall be declared as functions and may also be defined as macros. Function 14321 prototypes shall be provided for use with an ISO C standard compiler. 14322 char *asctime(const struct tm *); 14323 TSF char *asctime_r(const struct tm *restrict, char *restrict); 14324 clock_t clock(void); 14325 CPT int clock_getcpuclockid(pid_t, clockid_t *); 14326 TMR int clock_getres(clockid_t, struct timespec *); 14327 int clock_gettime(clockid_t, struct timespec *); 14328 CS int clock_nanosleep(clockid_t, int, const struct timespec *, 14329 struct timespec *); 14330 TMR int clock_settime(clockid_t, const struct timespec *); 14331 char *ctime(const time_t *); 14332 TSF char *ctime_r(const time_t *, char *); 14333 double difftime(time_t, time_t); 14334 XSI struct tm *getdate(const char *); 14335 struct tm *gmtime(const time_t *); 14336 struct tm *gmtime_r(const time_t *restrict, struct tm *restrict); 14337 struct tm *localtime(const time_t *); 14338 TSF struct tm *localtime_r(const time_t *restrict, struct tm *restrict); 14339 time_t mktime(struct tm *); 14340 TMR int nanosleep(const struct timespec *, struct timespec *); 14341 size_t strftime(char *restrict, size_t, const char *restrict, 14342 const struct tm *restrict); 14343 XSI char *strptime(const char *restrict, const char *restrict, 14344 struct tm *restrict); 14345 time_t time(time_t *); 14346 TMR int timer_create(clockid_t, struct sigevent *restrict, 14347 timer_t *restrict); 14348 int timer_delete(timer_t); 14349 int timer_gettime(timer_t, struct itimerspec *); 14350 int timer_getoverrun(timer_t); 14351 int timer_settime(timer_t, int, const struct itimerspec *restrict, 14352 struct itimerspec *restrict); 14353 void tzset(void); 14354 The following shall be declared as variables: 14355 XSI extern int daylight; 14356 extern long timezone; 14357 extern char *tzname[]; 428 Technical Standard (2000) (Draft July 28, 2000) Headers 14358 APPLICATION USAGE 14359 The range [0,61] for tm_sec allows for the occasional leap second or double leap second. 14360 tm_year is a signed value; therefore, years before 1900 may be represented. 14361 To obtain the number of clock ticks per second returned by the times( ) function, applications 14362 should call sysconf(_SC_CLK_TCK). 14363 RATIONALE 14364 None. 14365 FUTURE DIRECTIONS 14366 None. 14367 SEE ALSO 14368 , the System Interfaces volume of IEEE Std. 1003.1-200x, asctime( ), clock( ), 14369 clock_getcpuclockid( ), clock_getres( ), clock_nanosleep( ), ctime( ), difftime( ), getdate( ), gmtime( ), 14370 localtime( ), mktime( ), nanosleep( ), strftime( ), strptime( ), sysconf( ), time( ), timer_create( ), 14371 timer_delete( ), timer_getoverrun( ), tzname( ), tzset( ), utime( ), the Shell and Utilities volume of | 14372 IEEE Std. 1003.1-200x, daylight, timezone | 14373 CHANGE HISTORY 14374 First released in Issue 1. Derived from Issue 1 of the SVID. | 14375 Issue 4 14376 The symbolic name CLK_TCK is marked as an extension and LEGACY. Warnings about its use 14377 are also added to the DESCRIPTION. 14378 Reference to the header is added for the definitions of clock_t, size_t, and time_t. 14379 References to CLK_TCK are changed to CLOCKS_PER_SEC in part of the DESCRIPTION. The 14380 fact that CLOCKS_PER_SEC is always one millionth of a second on XSI-conformant systems is 14381 also marked as an extension. 14382 External declarations for daylight, timezone, and tzname are added. The first two are marked as 14383 extensions. 14384 The strptime( ) function is added to the list of functions declared in this header. 14385 A note about the settings of tm_sec is added to the APPLICATION USAGE section. 14386 The following changes are incorporated for alignment with the ISO C standard: 14387 * The function declarations in this header are expanded to full ISO C standard prototypes. 14388 * The range of tm_min is changed from [0,61] to [0,59]. 14389 * Possible settings of tm_isdst and their meanings are added. 14390 * The clock( ) and difftime( ) functions are added to the list of functions declared in this header. 14391 Issue 4, Version 2 14392 The following changes are incorporated for X/OPEN UNIX conformance: 14393 * The header provides a declaration for getdate_err. 14394 * The getdate( ) function is added to the list of functions declared in this header. 14395 Issue 5 14396 The DESCRIPTION is updated for alignment with the POSIX Realtime Extension and the POSIX 14397 Threads Extension. Base Definitions, Issue 6 429 Headers 14398 Issue 6 14399 The Open Group corrigenda item U035/6 has been applied. In the DESCRIPTION, the types 14400 clockid_t and timer_t have been described. 14401 The following changes are made for alignment with the ISO POSIX-1: 1996 standard: 14402 * The POSIX timer-related functions are now marked as part of the Timers option. | 14403 The symbolic name CLK_TCK is removed. Application usage is added describing how its 14404 equivalent functionality can be obtained using sysconf( ). 14405 The clock_getcpuclockid( ) function and manifest constants CLOCK_PROCESS_CPUTIME_ID and 14406 CLOCK_THREAD_CPUTIME_ID are added for alignment with IEEE Std. 1003.1d-1999. 14407 The manifest constant CLOCK_MONOTONIC and the clock_nanosleep( ) function are added for 14408 alignment with IEEE Std. 1003.1j-2000. | 14409 The following changes are made for alignment with the ISO/IEC 9899: 1999 standard: | 14410 * The range for seconds is changed from 0,61 to 0.60. | 14411 * The restrict keyword is added to the prototypes for asctime_r( ), gmtime_r( ), localtime_r ( ), | | 14412 strftime( ), strptime( ), timer_create( ), and timer_settime( ). | 430 Technical Standard (2000) (Draft July 28, 2000) Headers 14413 NAME | 14414 trace.h - tracing | 14415 SYNOPSIS | 14416 TRC #include | 14417 | 14418 DESCRIPTION | 14419 The header shall define the posix_trace_event_info structure that includes at least the | 14420 following members: | 14421 trace_event_id_t posix_event_id | 14422 pid_t posix_pid | 14423 void *posix_prog_address | 14424 int posix_truncation_status | 14425 struct timespec posix_timestamp | 14426 THR pthread_t posix_thread_id | 14427 | 14428 The header shall define the posix_trace_status_info structure that includes at least the | 14429 following members: | 14430 int posix_stream_status | 14431 int posix_stream_full_status | 14432 int posix_stream_overrun_status | 14433 TRL int posix_stream_flush_status | 14434 int posix_stream_flush_error | 14435 int posix_log_overrun_status | 14436 int posix_log_full_status | 14437 | 14438 The header shall define the following symbols: | 14439 POSIX_TRACE_RUNNING | 14440 POSIX_TRACE_SUSPENDED | 14441 POSIX_TRACE_FULL | 14442 POSIX_TRACE_NOT_FULL | 14443 POSIX_TRACE_NO_OVERRUN | 14444 POSIX_TRACE_OVERRUN | 14445 TRL POSIX_TRACE_FLUSHING | 14446 POSIX_TRACE_NOT_FLUSHING | 14447 POSIX_TRACE_NOT_TRUNCATED | 14448 POSIX_TRACE_TRUNCATED_READ | 14449 POSIX_TRACE_TRUNCATED_RECORD | 14450 TRL POSIX_TRACE_FLUSH | 14451 POSIX_TRACE_LOOP | 14452 POSIX_TRACE_UNTIL_FULL | 14453 TRI POSIX_TRACE_CLOSE_FOR_CHILD | 14454 POSIX_TRACE_INHERITED | 14455 TRL POSIX_TRACE_APPEND | 14456 POSIX_TRACE_LOOP | 14457 POSIX_TRACE_UNTIL_FULL | 14458 TEF POSIX_TRACE_FILTER | 14459 TRL POSIX_TRACE_FLUSH_START | 14460 POSIX_TRACE_FLUSH_STOP | 14461 POSIX_TRACE_OVERFLOW | Base Definitions, Issue 6 431 Headers 14462 POSIX_TRACE_RESUME | 14463 POSIX_TRACE_START | 14464 POSIX_TRACE_STOP | 14465 POSIX_TRACE_UNNAMED_USER_EVENT | 14466 The following types shall be defined as described in : | 14467 trace_attr_t | 14468 trace_id_t | 14469 trace_event_id_t | 14470 TEF trace_event_set_t | 14471 | 14472 The following shall be declared as functions and may also be declared as macros. Function | 14473 prototypes shall be provided for use with an ISO C standard compiler. | 14474 int posix_trace_attr_destroy(trace_attr_t *); | 14475 int posix_trace_attr_getclockres(const trace_attr_t *, | 14476 struct timespec *); | 14477 int posix_trace_attr_getcreatetime(const trace_attr_t *, | 14478 struct timespec *); | 14479 int posix_trace_attr_getgenversion(const trace_attr_t *, char *); | 14480 TRI int posix_trace_attr_getinherited(const trace_attr_t *, int *); | 14481 TRL int posix_trace_attr_getlogfullpolicy(const trace_attr_t *, int *); | 14482 int posix_trace_attr_getlogsize(const trace_attr_t *, size_t *); | 14483 int posix_trace_attr_getmaxdatasize(const trace_attr_t *, size_t *); | 14484 int posix_trace_attr_getmaxsystemeventsize(const trace_attr_t *, | 14485 size_t *); | 14486 int posix_trace_attr_getmaxusereventsize(const trace_attr_t *, | 14487 size_t, size_t *); | 14488 int posix_trace_attr_getname(const trace_attr_t *, char *); | 14489 int posix_trace_attr_getstreamfullpolicy(const trace_attr_t *, int *); | 14490 int posix_trace_attr_getstreamsize(const trace_attr_t *, size_t *); | 14491 int posix_trace_attr_init(trace_attr_t *); | 14492 TRI int posix_trace_attr_setinherited(trace_attr_t *, int); | 14493 TRL int posix_trace_attr_setlogfullpolicy(trace_attr_t *, int); | 14494 int posix_trace_attr_setlogsize(trace_attr_t *, size_t); | 14495 int posix_trace_attr_setmaxdatasize(trace_attr_t *, size_t); | 14496 int posix_trace_attr_setname(trace_attr_t *, const char *); | 14497 int posix_trace_attr_setstreamsize(trace_attr_t *, size_t); | 14498 int posix_trace_attr_setstreamfullpolicy(trace_attr_t *, int); | 14499 int posix_trace_clear(trace_id_t); | 14500 TRL int posix_trace_close(trace_id_t); | 14501 int posix_trace_create(pid_t, const trace_attr_t *, trace_id_t *); | 14502 TRL int posix_trace_create_withlog(pid_t, const trace_attr_t *, int, | 14503 trace_id_t *); | 14504 void posix_trace_event(trace_event_id_t, const void *, size_t); | 14505 int posix_trace_eventid_equal(trace_id_t, trace_eventid_t, | 14506 trace_eventid_t); | 14507 int posix_trace_eventid_get_name(trace_id_t, trace_eventid_t, char *); | 14508 int posix_trace_eventid_open(const char *, trace_event_id_t *); | 14509 int posix_trace_eventtypelist_getnext_id(trace_id_t, trace_eventid_t *, | 14510 int *); | 14511 int posix_trace_eventtypelist_rewind(trace_id_t); | 432 Technical Standard (2000) (Draft July 28, 2000) Headers 14512 TEF int posix_trace_eventset_add(trace_event_id_t, trace_event_set_t *); | 14513 int posix_trace_eventset_del(trace_event_id_t, trace_event_set_t *); | 14514 int posix_trace_eventset_empty(trace_event_set_t *); | 14515 int posix_trace_eventset_fill(trace_event_set_t *, int); | 14516 int posix_trace_eventset_ismember(trace_event_id_t, | 14517 const trace_event_set_t *, int *); | 14518 int posix_trace_flush(trace_id_t); | 14519 int posix_trace_get_attr(trace_id_t, trace_attr_t *); | 14520 TEF int posix_trace_get_filter(trace_id_t, trace_event_set_t *); | 14521 int posix_trace_get_status(trace_id_t, | 14522 struct posix_trace_status_info *); | 14523 int posix_trace_getnext_event(trace_id_t, | 14524 struct posix_trace_event_info *, void *, size_t, size_t *, | 14525 int *); | 14526 TRL int posix_trace_open(int, trace_id_t *); | 14527 int posix_trace_rewind(trace_id_t); | 14528 TEF int posix_trace_set_filter(trace_id_t, const trace_event_set_t *, int); | 14529 int posix_trace_shutdown(trace_id_t); | 14530 int posix_trace_start(trace_id_t); | 14531 int posix_trace_stop(trace_id_t); | 14532 TMO int posix_trace_timedgetnext_event(trace_id_t, | 14533 struct posix_trace_event_info *, void *, size_t, size_t *, | 14534 int *, const struct timespec *); | 14535 TEF int posix_trace_trid_eventid_open(trace_id_t, const char *, | 14536 trace_eventid_t *); | 14537 int posix_trace_trygetnext_event(trace_id_t, | 14538 struct posix_trace_event_info *, void *, size_t, size_t *, | 14539 int *); | 14540 APPLICATION USAGE | 14541 None. | 14542 RATIONALE | 14543 None. | 14544 FUTURE DIRECTIONS | 14545 None. | 14546 SEE ALSO | 14547 , the System Interfaces volume of IEEE Std. 1003.1-200x, Section 2.11, Tracing, the | 14548 System Interfaces volume of IEEE Std. 1003.1-200x, posix_trace_attr_destroy( ), | 14549 posix_trace_attr_getclockres( ), posix_trace_attr_getcreatetime( ), posix_trace_attr_getgenversion( ), | 14550 posix_trace_attr_getinherited( ), posix_trace_attr_getlogfullpolicy( ), posix_trace_attr_getlogsize( ), | 14551 posix_trace_attr_getmaxdatasize( ), posix_trace_attr_getmaxsystemeventsize( ), | 14552 posix_trace_attr_getmaxusereventsize( ), posix_trace_attr_getname( ), | 14553 posix_trace_attr_getstreamfullpolicy( ), posix_trace_attr_getstreamsize( ), posix_trace_attr_init( ), | 14554 posix_trace_attr_setinherited( ), posix_trace_attr_setlogfullpolicy( ), posix_trace_attr_setlogsize( ), | 14555 posix_trace_attr_setmaxdatasize( ), posix_trace_attr_setname( ), posix_trace_attr_setstreamsize( ), | 14556 posix_trace_attr_setstreamfullpolicy( ), posix_trace_clear( ), posix_trace_close( ), posix_trace_create( ), | 14557 posix_trace_create_withlog( ), posix_trace_event( ), posix_trace_eventid_equal( ), | 14558 posix_trace_eventid_get_name( ), posix_trace_eventid_open( ), posix_trace_eventtypelist_getnext_id( ), | 14559 posix_trace_eventtypelist_rewind( ), posix_trace_eventset_add( ), posix_trace_eventset_del( ), | 14560 posix_trace_eventset_empty( ), posix_trace_eventset_fill( ), posix_trace_eventset_ismember( ), | 14561 posix_trace_flush( ), posix_trace_get_attr( ), posix_trace_get_filter( ), posix_trace_get_status( ), | Base Definitions, Issue 6 433 Headers 14562 posix_trace_getnext_event( ), posix_trace_open( ), posix_trace_rewind( ), posix_trace_set_filter( ), | 14563 posix_trace_shutdown( ), posix_trace_start( ), posix_trace_stop( ), posix_trace_timedgetnext_event( ), | 14564 posix_trace_trid_eventid_open( ), posix_trace_trygetnext_event( ) | 14565 CHANGE ~ HISTORY || 14566 First released in Issue 6. Derived from IEEE Std. 1003.1q-2000. | 434 Technical Standard (2000) (Draft July 28, 2000) Headers 14567 NAME 14568 ucontext.h - user context | 14569 SYNOPSIS 14570 XSI #include 14571 14572 DESCRIPTION 14573 The header shall define the mcontext_t type through typedef. 14574 The header shall define the ucontext_t type as a structure that shall include at least 14575 the following members: 14576 ucontext_t *uc_link Pointer to the context that is resumed 14577 when this context returns. 14578 sigset_t uc_sigmask The set of signals that are blocked when this 14579 context is active. 14580 stack_t uc_stack The stack used by this context. 14581 mcontext_t uc_mcontext A machine-specific representation of the saved 14582 context. 14583 The types sigset_t and stack_t shall be defined as in . 14584 The following shall be declared as functions and may also be defined as macros, Function 14585 prototypes shall be provided for use with an ISO C standard compiler. 14586 int getcontext(ucontext_t *); 14587 int setcontext(const ucontext_t *); 14588 void makecontext(ucontext_t *, void (*)(void), int, ...); 14589 int swapcontext(ucontext_t *restrict, const ucontext_t *restrict); 14590 APPLICATION USAGE 14591 None. 14592 RATIONALE 14593 None. 14594 FUTURE DIRECTIONS 14595 None. 14596 SEE ALSO 14597 , the System Interfaces volume of IEEE Std. 1003.1-200x, getcontext( ), makecontext( ), 14598 sigaction( ), sigprocmask( ), sigaltstack( ) 14599 CHANGE HISTORY 14600 First released in Issue 4, Version 2. Base Definitions, Issue 6 435 Headers 14601 NAME 14602 ulimit.h - ulimit commands 14603 SYNOPSIS 14604 XSI #include 14605 14606 DESCRIPTION 14607 The header shall define the symbolic constants used by the ulimit( ) function. 14608 Symbolic constants: 14609 UL_GETFSIZE Get maximum file size. 14610 UL_SETFSIZE Set maximum file size. 14611 The following shall be declared as a function and may also be defined as a macro. Function 14612 prototypes shall be provided for use with an ISO C standard compiler. 14613 long ulimit(int, ...); 14614 APPLICATION USAGE 14615 None. 14616 RATIONALE 14617 None. 14618 FUTURE DIRECTIONS 14619 None. 14620 SEE ALSO 14621 The System Interfaces volume of IEEE Std. 1003.1-200x, ulimit( ) 14622 CHANGE HISTORY 14623 First released in Issue 3. 14624 Issue 4 14625 The function declarations in this header are expanded to full ISO C standard prototypes. 436 Technical Standard (2000) (Draft July 28, 2000) Headers 14626 NAME 14627 unistd.h - standard symbolic constants and types 14628 SYNOPSIS 14629 #include 14630 DESCRIPTION 14631 The header defines miscellaneous symbolic constants and types, and declares 14632 miscellaneous functions. The actual value of the constants are unspecified except as shown. The 14633 contents of this header are shown below. 14634 Version Test Macros 14635 The following symbolic constants shall be defined: 14636 _POSIX_VERSION 14637 Integer value indicating version of IEEE Std. 1003.1-200x (C-language binding). The value is 14638 200xxxL. This value shall be used for systems that conform to IEEE Std. 1003.1-200x. | 14639 _POSIX2_VERSION | 14640 Integer value indicating version of the Shell and Utilities volume of IEEE Std. 1003.1-200x. | 14641 XSI _XOPEN_VERSION 14642 Integer value indicating version of the X/Open Portability Guide to which the 14643 implementation conforms. The value is 600. 14644 XSI _XOPEN_XCU_VERSION is defined as an integer value indicating the version of the Shell and | 14645 Utilities volume of IEEE Std. 1003.1-200x to which the implementation conforms. If the value is | 14646 -1, no commands and utilities are provided on the implementation. If the value is greater than | 14647 or equal to 4, the functionality associated with the following symbols is also supported (see 14648 Constants for Options and Option Groups (on page 438) and Constants for Profiling Option 14649 Groups (on page 444)): 14650 _POSIX2_C_BIND 14651 _POSIX2_CHAR_TERM 14652 _POSIX2_LOCALEDEF 14653 _POSIX2_UPE 14654 _POSIX2_VERSION 14655 If _XOPEN_XCU_VERSION is not defined, use the sysconf( ) function to determine which | 14656 features are supported. 14657 Each of the following symbolic constants shall be defined only if the implementation supports 14658 the indicated version of the X/Open Portability Guide: 14659 XSI _XOPEN_UNIX 14660 X/Open CAE Specification, January 1997, System Interfaces and Headers, Issue 5 14661 (ISBN: 1-85912-181-0, C606). 14662 _XOPEN_XPG2 14663 X/Open Portability Guide, Volume 2, January 1987, XVS System Calls and Libraries 14664 (ISBN: 0-444-70175-3). 14665 _XOPEN_XPG3 14666 X/Open Specification, February 1992, System Interfaces and Headers, Issue 3 14667 (ISBN: 1-872630-37-5, C212); this specification was formerly X/Open Portability Guide, 14668 Issue 3, Volume 2, January 1989, XSI System Interface and Headers (ISBN: 0-13-685843-0, 14669 XO/XPG/89/003). Base Definitions, Issue 6 437 Headers 14670 _XOPEN_XPG4 14671 X/Open CAE Specification, July 1992, System Interfaces and Headers, Issue 4 14672 (ISBN: 1-872630-47-2, C202). 14673 Constants for Options and Option Groups 14674 The following symbolic constants, if defined in , shall have a value of -1, 0, or greater, 14675 unless otherwise specified below. If these are undefined, the sysconf( ) function can be used to 14676 determine whether the option is provided for a particular invocation of the application. 14677 If a symbolic constant is defined with the value -1, the option is not supported. Headers, data 14678 types, and function interfaces required only for the option need not be supplied. An application 14679 that attempts to use anything associated only with the option is considered to be requiring an 14680 extension. 14681 If a symbolic constant is defined with a value greater than zero, the option shall always be 14682 supported when the application is executed. All headers, data types, and functions shall be 14683 present and shall operate as specified. 14684 If a symbolic constant is defined with the value zero, all headers, data types, and functions shall 14685 be present. The application must check at runtime to see whether the option is supported by 14686 calling sysconf( ) with the indicated name parameter. 14687 Unless explicitly specified otherwise, the behavior of functions associated with an unsupported 14688 option is unspecified, and an application that uses such functions without first checking 14689 sysconf( ) is considered to be requiring an extension. | 14690 For conformance requirements, refer to Chapter 2 (on page 19). 14691 ADV _POSIX_ADVISORY_INFO 14692 The implementation supports the Advisory Information option. If this symbol has a value 14693 other than -1, it shall have the value 200ymmL, the date of approval of 14694 IEEE Std. 1003.1-200x. 14695 AIO _POSIX_ASYNCHRONOUS_IO 14696 The implementation supports the Asynchronous Input and Output option. If this symbol | 14697 has a value other than -1, it shall have the value 200ymmL, the date of approval of | 14698 IEEE Std. 1003.1-200x. | 14699 BAR _POSIX_BARRIERS 14700 The implementation supports the Barriers option. If this symbol has a value other than -1, it 14701 shall have the value 200ymmL, the date of approval of IEEE Std. 1003.1-200x. 14702 _POSIX_CHOWN_RESTRICTED 14703 The use of chown( ) and fchown( ) is restricted to a process with appropriate privileges, and 14704 to changing the group ID of a file only to the effective group ID of the process or to one of 14705 its supplementary group IDs. 14706 CS _POSIX_CLOCK_SELECTION 14707 The implementation supports the Clock Selection option. If this symbol has a value other 14708 than -1, it shall have the value 200ymmL, the date of approval of IEEE Std. 1003.1-200x. 14709 CPT _POSIX_CPUTIME 14710 The implementation supports the Process CPU-Time Clocks option. If this symbol has a 14711 value other than -1, it shall have the value 200ymmL, the date of approval of 14712 IEEE Std. 1003.1-200x. 14713 FSC _POSIX_FSYNC 14714 The implementation supports the File Synchronization option. If this symbol has a value | 438 Technical Standard (2000) (Draft July 28, 2000) Headers 14715 other than -1, it shall have the value 200ymmL, the date of approval of | 14716 IEEE Std. 1003.1-200x. | 14717 _POSIX_JOB_CONTROL 14718 The implementation supports job control. This is always set to a value greater than zero. 14719 MF _POSIX_MAPPED_FILES 14720 The implementation supports the Memory Mapped Files option. If this symbol has a value | 14721 other than -1, it shall have the value 200ymmL, the date of approval of | 14722 IEEE Std. 1003.1-200x. | 14723 ML _POSIX_MEMLOCK 14724 The implementation supports the Process Memory Locking option. If this symbol has a | 14725 value other than -1, it shall have the value 200ymmL, the date of approval of | 14726 IEEE Std. 1003.1-200x. | 14727 MLR _POSIX_MEMLOCK_RANGE 14728 The implementation supports the Range Memory Locking option. If this symbol has a value | 14729 other than -1, it shall have the value 200ymmL, the date of approval of | 14730 IEEE Std. 1003.1-200x. | 14731 MPR _POSIX_MEMORY_PROTECTION 14732 The implementation supports the Memory Protection option. If this symbol has a value | 14733 other than -1, it shall have the value 200ymmL, the date of approval of | 14734 IEEE Std. 1003.1-200x. | 14735 MSG _POSIX_MESSAGE_PASSING 14736 The implementation supports the Message Passing option. If this symbol has a value other | 14737 than -1, it shall have the value 200ymmL, the date of approval of IEEE Std. 1003.1-200x. | 14738 MON _POSIX_MONOTONIC_CLOCK 14739 The implementation supports the Monotonic Clock option. If this symbol has a value other 14740 than -1, it shall have the value 200ymmL, the date of approval of IEEE Std. 1003.1-200x. 14741 _POSIX_NO_TRUNC 14742 Path name components longer than {NAME_MAX} generate an error. 14743 PIO _POSIX_PRIORITIZED_IO 14744 The implementation supports the Prioritized Input and Output option. If this symbol has a | 14745 value other than -1, it shall have the value 200ymmL, the date of approval of | 14746 IEEE Std. 1003.1-200x. | 14747 PS _POSIX_PRIORITY_SCHEDULING 14748 The implementation supports the Process Scheduling option. If this symbol has a value | 14749 other than -1, it shall have the value 200ymmL, the date of approval of | 14750 IEEE Std. 1003.1-200x. | 14751 THR _POSIX_READER_WRITER_LOCKS | 14752 The implementation supports the Read-Write Locks option. This is always set to a value | 14753 greater than zero if the Threads option is supported. If this symbol has a value other than | 14754 -1, it shall have the value 200ymmL, the date of approval of IEEE Std. 1003.1-200x. | 14755 RTS _POSIX_REALTIME_SIGNALS 14756 The implementation supports the Realtime Signals Extension option. If this symbol has a | 14757 value other than -1, it shall have the value 200ymmL, the date of approval of | 14758 IEEE Std. 1003.1-200x. | 14759 _POSIX_REGEXP | 14760 The implementation supports the Regular Expression Handling option. This is always set | Base Definitions, Issue 6 439 Headers 14761 to a value greater than zero. | 14762 _POSIX_SAVED_IDS 14763 Each process has a saved set-user-ID and a saved set-group-ID. The behavior of the setuid( ), 14764 setgid( ), and kill( ) functions shall be dependent on the values of the saved set-user-ID and | 14765 the saved get-group-ID, respectively. This is always set to a value greater than zero. | 14766 SEM _POSIX_SEMAPHORES 14767 The implementation supports the Semaphores option. If this symbol has a value other than | 14768 -1, it shall have the value 200ymmL, the date of approval of IEEE Std. 1003.1-200x. | 14769 SHM _POSIX_SHARED_MEMORY_OBJECTS 14770 The implementation supports the Shared Memory Objects option. If this symbol has a value | 14771 other than -1, it shall have the value 200ymmL, the date of approval of | 14772 IEEE Std. 1003.1-200x. | 14773 SH _POSIX_SHELL 14774 The implementation supports the POSIX shell. This is always set to a value greater than 14775 zero. 14776 SPN _POSIX_SPAWN 14777 The implementation supports the Spawn option. If this symbol has a value other than -1, it 14778 shall have the value 200ymmL, the date of approval of IEEE Std. 1003.1-200x. 14779 SPI _POSIX_SPIN_LOCKS 14780 The implementation supports the Spin Locks option. If this symbol has a value other than 14781 -1, it shall have the value 200ymmL, the date of approval of IEEE Std. 1003.1-200x. 14782 SS _POSIX_SPORADIC_SERVER 14783 The implementation supports the Process Sporadic Server option. If this symbol has a value 14784 other than -1, it shall have the value 200ymmL, the date of approval of 14785 IEEE Std. 1003.1-200x. 14786 SIO _POSIX_SYNCHRONIZED_IO 14787 The implementation supports the Synchronized Input and Output option. If this symbol | 14788 has a value other than -1, it shall have the value 200ymmL, the date of approval of | 14789 IEEE Std. 1003.1-200x. | 14790 TSA _POSIX_THREAD_ATTR_STACKADDR 14791 The implementation supports the Thread Stack Address Attribute option. If this symbol | 14792 has a value other than -1, it shall have the value 200ymmL, the date of approval of | 14793 IEEE Std. 1003.1-200x. | 14794 TSS _POSIX_THREAD_ATTR_STACKSIZE 14795 The implementation supports the Thread Stack Address Size option. If this symbol has a | 14796 value other than -1, it shall have the value 200ymmL, the date of approval of | 14797 IEEE Std. 1003.1-200x. | 14798 TCT _POSIX_THREAD_CPUTIME 14799 The implementation supports the Thread CPU-Time Clocks option. If this symbol has a 14800 value other than -1, it shall have the value 200ymmL, the date of approval of 14801 IEEE Std. 1003.1-200x. 14802 TPI _POSIX_THREAD_PRIO_INHERIT 14803 The implementation supports the Threads Priority Inheritance option. If this symbol has a | 14804 value other than -1, it shall have the value 200ymmL, the date of approval of | 14805 IEEE Std. 1003.1-200x. | 440 Technical Standard (2000) (Draft July 28, 2000) Headers 14806 TPP _POSIX_THREAD_PRIO_PROTECT 14807 The implementation supports the Thread Priority Protection option. If this symbol has a | 14808 value other than -1, it shall have the value 200ymmL, the date of approval of | 14809 IEEE Std. 1003.1-200x. | 14810 TPS _POSIX_THREAD_PRIORITY_SCHEDULING 14811 The implementation supports the Thread Execution Scheduling option. If this symbol has a | 14812 value other than -1, it shall have the value 200ymmL, the date of approval of | 14813 IEEE Std. 1003.1-200x. | 14814 TSH _POSIX_THREAD_PROCESS_SHARED 14815 The implementation supports the Thread Process-Shared Synchronization option. If this | 14816 symbol has a value other than -1, it shall have the value 200ymmL, the date of approval of | 14817 IEEE Std. 1003.1-200x. | 14818 TSF _POSIX_THREAD_SAFE_FUNCTIONS 14819 The implementation supports the Thread-Safe Functions option. If this symbol has a value | 14820 other than -1, it shall have the value 200ymmL, the date of approval of | 14821 IEEE Std. 1003.1-200x. | 14822 TSP _POSIX_THREAD_SPORADIC_SERVER 14823 The implementation supports the Thread Sporadic Server option. If this symbol has a value 14824 other than -1, it shall have the value 200ymmL, the date of approval of 14825 IEEE Std. 1003.1-200x. 14826 THR _POSIX_THREADS 14827 The implementation supports the Threads option. If this symbol has a value other than -1, it | 14828 shall have the value 200ymmL, the date of approval of IEEE Std. 1003.1-200x. | 14829 TMR _POSIX_TIMERS 14830 The implementation supports the Timers option. If this symbol has a value other than -1, it | 14831 shall have the value 200ymmL, the date of approval of IEEE Std. 1003.1-200x. | 14832 TMO _POSIX_TIMEOUTS 14833 The implementation supports the Timeouts option. If this symbol has a value other than -1, 14834 it shall have the value 200ymmL, the date of approval of IEEE Std. 1003.1-200x. | 14835 TRC _POSIX_TRACE | 14836 The implementation supports the Trace option. | 14837 TEF _POSIX_TRACE_EVENT_FILTER | 14838 The implementation supports the Trace Event Filter option. | 14839 TRL _POSIX_TRACE_LOG | 14840 The implementation supports the Trace Log option. | 14841 TRI _POSIX_TRACE_INHERIT | 14842 The implementation supports the Trace Inherit option. | 14843 TYM _POSIX_TYPED_MEMORY_OBJECTS 14844 The implementation supports the Typed Memory Objects option. If this symbol has a value 14845 other than -1, it shall have the value 200ymmL, the date of approval of 14846 IEEE Std. 1003.1-200x. 14847 _POSIX_VDISABLE 14848 Terminal special characters defined in can be disabled using this character 14849 value. Base Definitions, Issue 6 441 Headers 14850 _POSIX2_C_BIND 14851 The implementation supports the C-Language Binding option. This always has the value | 14852 200ymmL, the date of approval of IEEE Std. 1003.1-200x. | 14853 CD _POSIX2_C_DEV 14854 The implementation supports the C-Language Development Utilities option. If this symbol | 14855 has a value other than -1, it shall have the value 200ymmL, the date of approval of | 14856 IEEE Std. 1003.1-200x. | 14857 _POSIX2_CHAR_TERM 14858 The implementation supports at least one terminal type. 14859 FD _POSIX2_FORT_DEV 14860 The implementation supports the FORTRAN Development Utilities option. If this symbol | 14861 has a value other than -1, it shall have the value 200ymmL, the date of approval of | 14862 IEEE Std. 1003.1-200x. | 14863 FR _POSIX2_FORT_RUN 14864 The implementation supports the FORTRAN Runtime Utilities option. If this symbol has a | 14865 value other than -1, it shall have the value 200ymmL, the date of approval of | 14866 IEEE Std. 1003.1-200x. | 14867 _POSIX2_LOCALEDEF 14868 The implementation supports the creation of locales by the localedef utility. If this symbol | 14869 has a value other than -1, it shall have the value 200ymmL, the date of approval of | 14870 IEEE Std. 1003.1-200x. | 14871 BE _POSIX2_PBS 14872 The implementation supports the Batch Environment Services and Utilities option. If this | 14873 symbol has a value other than -1, it shall have the value 200ymmL, the date of approval of | 14874 IEEE Std. 1003.1-200x. | 14875 BE _POSIX2_PBS_ACCOUNTING 14876 The implementation supports the Batch Accounting option. If this symbol has a value other | 14877 than -1, it shall have the value 200ymmL, the date of approval of IEEE Std. 1003.1-200x. | 14878 BE _POSIX2_PBS_CHECKPOINT 14879 The implementation supports the Batch Checkpoint/Restart option. If this symbol has a | 14880 value other than -1, it shall have the value 200ymmL, the date of approval of | 14881 IEEE Std. 1003.1-200x. | 14882 BE _POSIX2_PBS_LOCATE 14883 The implementation supports the Locate Batch Job Request option. If this symbol has a | 14884 value other than -1, it shall have the value 200ymmL, the date of approval of | 14885 IEEE Std. 1003.1-200x. | 14886 BE _POSIX2_PBS_MESSAGE 14887 The implementation supports the Batch Job Message Request option. If this symbol has a | 14888 value other than -1, it shall have the value 200ymmL, the date of approval of | 14889 IEEE Std. 1003.1-200x. | 14890 BE _POSIX2_PBS_TRACK 14891 The implementation supports the Track Batch Job Request option. If this symbol has a value | 14892 other than -1, it shall have the value 200ymmL, the date of approval of | 14893 IEEE Std. 1003.1-200x. | 14894 SD _POSIX2_SW_DEV 14895 The implementation supports the Software Development Utilities option. If this symbol has | 442 Technical Standard (2000) (Draft July 28, 2000) Headers 14896 a value other than -1, it shall have the value 200ymmL, the date of approval of | 14897 IEEE Std. 1003.1-200x. | 14898 UP _POSIX2_UPE 14899 The implementation supports the User Portability Utilities option. If this symbol has a value | 14900 other than -1, it shall have the value 200ymmL, the date of approval of | 14901 IEEE Std. 1003.1-200x. | 14902 _V6_ILP32_OFF32 | 14903 The implementation provides a C-language compilation environment with 32-bit int, long, | 14904 pointer, and off_t types. | 14905 _V6_ILP32_OFFBIG | 14906 The implementation provides a C-language compilation environment with 32-bit int, long, | 14907 and pointer types and an off_t type using at least 64 bits. | 14908 _V6_LP64_OFF64 | 14909 The implementation provides a C-language compilation environment with 32-bit int and | 14910 64-bit long, pointer, and off_t types. | 14911 _V6_LPBIG_OFFBIG | 14912 The implementation provides a C-language compilation environment with an int type | 14913 using at least 32 bits and long, pointer, and off_t types using at least 64 bits. | 14914 XSI _XBS5_ILP32_OFF32 (LEGACY) | 14915 The implementation provides a C-language compilation environment with 32-bit int, long, 14916 pointer, and off_t types. | 14917 XSI _XBS5_ILP32_OFFBIG (LEGACY) | 14918 The implementation provides a C-language compilation environment with 32-bit int, long, 14919 and pointer types and an off_t type using at least 64 bits. | 14920 XSI _XBS5_LP64_OFF64 (LEGACY) | 14921 The implementation provides a C-language compilation environment with 32-bit int and 14922 64-bit long, pointer, and off_t types. | 14923 XSI _XBS5_LPBIG_OFFBIG (LEGACY) | 14924 The implementation provides a C-language compilation environment with an int type 14925 using at least 32 bits and long, pointer, and off_t types using at least 64 bits. 14926 XSI _XOPEN_CRYPT 14927 The implementation supports the X/Open Encryption Option Group. 14928 _XOPEN_ENH_I18N 14929 The implementation supports the Issue 4, Version 2 Enhanced Internationalization Option 14930 Group. This is always set to a value other than -1. 14931 _XOPEN_LEGACY 14932 The implementation supports the Legacy Option Group. 14933 _XOPEN_REALTIME 14934 The implementation supports the X/Open Realtime Option Group. 14935 _XOPEN_REALTIME_THREADS 14936 The implementation supports the X/Open Realtime Threads Option Group. 14937 _XOPEN_SHM 14938 The implementation supports the Issue 4, Version 2 Shared Memory Option Group. This is 14939 always set to a value other than -1. Base Definitions, Issue 6 443 Headers 14940 _XOPEN_STREAMS 14941 The implementation supports the XSI STREAMS Option Group. 14942 Constants for Profiling Option Groups 14943 The following symbolic constants shall be defined to have the value -1 if the implementation 14944 never provides the Profiling Option Group, and to have a value other than -1 if the 14945 implementation always provides the Profiling Option Group. If these are undefined, the 14946 sysconf( ) function can be used to determine whether the Profiling Option Group is provided for 14947 a particular invocation of the application. 14948 For conformance requirements, refer to Chapter 2 (on page 19). 14949 * _POSIX_BASE 14950 * _POSIX_C_LANG_SUPPORT 14951 * _POSIX_C_LANG_SUPPORT_R 14952 * _POSIX_DEVICE_IO 14953 * _POSIX_DEVICE_SPECIFIC 14954 * _POSIX_DEVICE_SPECIFIC_R 14955 * _POSIX_FD_MGMT 14956 * _POSIX_FIFO 14957 * _POSIX_FILE_ATTRIBUTES 14958 * _POSIX_FILE_LOCKING 14959 * _POSIX_FILE_SYSTEM 14960 * _POSIX_JOB_CONTROL 14961 * _POSIX_MULTIPLE_PROCESS 14962 * _POSIX_NETWORKING 14963 * _POSIX_PIPE 14964 * _POSIX_SIGNALS 14965 * _POSIX_SINGLE_PROCESS 14966 * _POSIX_SYSTEM_DATABASE 14967 * _POSIX_SYSTEM_DATABASE_R 14968 * _POSIX_USER_GROUPS 14969 * _POSIX_USER_GROUPS_R 14970 Execution-Time Symbolic Constants 14971 If any of the following constants are not defined in the header, the value shall vary 14972 depending on the file to which it is applied. 14973 If any of the following constants are defined to have value -1 in the header, the 14974 implementation shall not provide the option on any file; if any are defined to have a value other 14975 than -1 in the header, the implementation shall provide the option on all applicable 14976 files. 444 Technical Standard (2000) (Draft July 28, 2000) Headers 14977 All of the following constants, whether defined in or not, may be queried with 14978 respect to a specific file using the pathconf( ) or fpathconf( ) functions: 14979 _POSIX_ASYNC_IO 14980 Asynchronous input or output operations may be performed for the associated file. 14981 _POSIX_PRIO_IO 14982 Prioritized input or output operations may be performed for the associated file. 14983 _POSIX_SYNC_IO 14984 Synchronized input or output operations may be performed for the associated file. 14985 Constants for Functions 14986 The following symbolic constant shall be defined: 14987 NULL Null pointer 14988 The following symbolic constants shall be defined for the access( ) function: 14989 F_OK Test for existence of file. 14990 R_OK Test for read permission. 14991 W_OK Test for write permission. 14992 X_OK Test for execute (search) permission. 14993 The constants F_OK, R_OK, W_OK, and X_OK and the expressions R_OK|W_OK, R_OK|X_OK, 14994 and R_OK|W_OK|X_OK shall all have distinct values. 14995 The following symbolic constants shall be defined for the confstr( ) function: 14996 _CS_PATH 14997 This is the value for the PATH environment variable that finds all standard utilities. | 14998 _CS_V6_ILP32_OFF32_CFLAGS | 14999 If sysconf(_SC_V6_ILP32_OFF32) returns -1, the meaning of this value is unspecified. | 15000 Otherwise, this value is the set of initial options to be given to the cc and c99 utilities to | 15001 build an application using a programming model with 32-bit int, long, pointer, and off_t | 15002 types. | 15003 _CS_V6_ILP32_OFF32_LDFLAGS | 15004 If sysconf(_SC_V6_ILP32_OFF32) returns -1, the meaning of this value is unspecified. | 15005 Otherwise, this value is the set of final options to be given to the cc and c99 utilities to build | 15006 an application using a programming model with 32-bit int, long, pointer, and off_t types. | 15007 _CS_V6_ILP32_OFF32_LIBS | 15008 If sysconf(_SC_V6_ILP32_OFF32) returns -1, the meaning of this value is unspecified. | 15009 Otherwise, this value is the set of libraries to be given to the cc and c99 utilities to build an | 15010 application using a programming model with 32-bit int, long, pointer, and off_t types. | 15011 _CS_V6_ILP32_OFF32_LINTFLAGS | 15012 If sysconf(_SC_V6_ILP32_OFF32) returns -1, the meaning of this value is unspecified. | 15013 Otherwise, this value is the set of options to be given to the lint utility to check application | 15014 source using a programming model with 32-bit int, long, pointer, and off_t types. | 15015 _CS_V6_ILP32_OFFBIG_CFLAGS | 15016 If sysconf(_SC_V6_ILP32_OFFBIG) returns -1, the meaning of this value is unspecified. | 15017 Otherwise, this value is the set of initial options to be given to the cc and c99 utilities to | 15018 build an application using a programming model with 32-bit int, long, and pointer types, | Base Definitions, Issue 6 445 Headers 15019 and an off_t type using at least 64 bits. | 15020 _CS_V6_ILP32_OFFBIG_LDFLAGS | 15021 If sysconf(_SC_V6_ILP32_OFFBIG) returns -1, the meaning of this value is unspecified. | 15022 Otherwise, this value is the set of final options to be given to the cc and c99 utilities to build | 15023 an application using a programming model with 32-bit int, long, and pointer types, and an | 15024 off_t type using at least 64 bits. | 15025 _CS_V6_ILP32_OFFBIG_LIBS | 15026 If sysconf(_SC_V6_ILP32_OFFBIG) returns -1, the meaning of this value is unspecified. | 15027 Otherwise, this value is the set of libraries to be given to the cc and c99 utilities to build an | 15028 application using a programming model with 32-bit int, long, and pointer types, and an | 15029 off_t type using at least 64 bits. | 15030 _CS_V6_ILP32_OFFBIG_LINTFLAGS | 15031 If sysconf(_SC_V6_ILP32_OFFBIG) returns -1, the meaning of this value is unspecified. | 15032 Otherwise, this value is the set of options to be given to the lint utility to check an | 15033 application using a programming model with 32-bit int, long, and pointer types, and an | 15034 off_t type using at least 64 bits. | 15035 _CS_V6_LP64_OFF64_CFLAGS | 15036 If sysconf(_SC_V6_LP64_OFF64) returns -1, the meaning of this value is unspecified. | 15037 Otherwise, this value is the set of initial options to be given to the cc and c99 utilities to | 15038 build an application using a programming model with 64-bit int, long, pointer, and off_t | 15039 types. | 15040 _CS_V6_LP64_OFF64_LDFLAGS | 15041 If sysconf(_SC_V6_LP64_OFF64) returns -1, the meaning of this value is unspecified. | 15042 Otherwise, this value is the set of final options to be given to the cc and c99 utilities to build | 15043 an application using a programming model with 64-bit int, long, pointer, and off_t types. | 15044 _CS_V6_LP64_OFF64_LIBS | 15045 If sysconf(_SC_V6_LP64_OFF64) returns -1, the meaning of this value is unspecified. | 15046 Otherwise, this value is the set of libraries to be given to the cc and c99 utilities to build an | 15047 application using a programming model with 64-bit int, long, pointer, and off_t types. | 15048 _CS_V6_LP64_OFF64_LINTFLAGS | 15049 If sysconf(_SC_V6_LP64_OFF64) returns -1, the meaning of this value is unspecified. | 15050 Otherwise, this value is the set of options to be given to the lint utility to check application | 15051 source using a programming model with 64-bit int, long, pointer, and off_t types. | 15052 _CS_V6_LPBIG_OFFBIG_CFLAGS | 15053 If sysconf(_SC_V6_LPBIG_OFFBIG) returns -1, the meaning of this value is unspecified. | 15054 Otherwise, this value is the set of initial options to be given to the cc and c99 utilities to | 15055 build an application using a programming model with an int type using at least 32 bits and | 15056 long, pointer, and off_t types using at least 64 bits. | 15057 _CS_V6_LPBIG_OFFBIG_LDFLAGS | 15058 If sysconf(_SC_V6_LPBIG_OFFBIG) returns -1, the meaning of this value is unspecified. | 15059 Otherwise, this value is the set of final options to be given to the cc and c99 utilities to build | 15060 an application using a programming model with an int type using at least 32 bits and long, | 15061 pointer, and off_t types using at least 64 bits. | 15062 _CS_V6_LPBIG_OFFBIG_LIBS | 15063 If sysconf(_SC_V6_LPBIG_OFFBIG) returns -1, the meaning of this value is unspecified. | 15064 Otherwise, this value is the set of libraries to be given to the cc and c99 utilities to build an | 15065 application using a programming model with an int type using at least 32 bits and long, | 446 Technical Standard (2000) (Draft July 28, 2000) Headers 15066 pointer, and off_t types using at least 64 bits. | 15067 _CS_V6_LPBIG_OFFBIG_LINTFLAGS | 15068 If sysconf(_SC_V6_LPBIG_OFFBIG) returns -1, the meaning of this value is unspecified. | 15069 Otherwise, this value is the set of options to be given to the lint utility to check application | 15070 source using a programming model with an int type using at least 32 bits and long, pointer, | 15071 and off_t types using at least 64 bits. | 15072 XSI _CS_XBS5_ILP32_OFF32_CFLAGS (LEGACY) | 15073 If sysconf(_SC_XBS5_ILP32_OFF32) returns -1, the meaning of this value is unspecified. 15074 Otherwise, this value is the set of initial options to be given to the cc and c99 utilities to | 15075 build an application using a programming model with 32-bit int, long, pointer, and off_t 15076 types. | 15077 XSI _CS_XBS5_ILP32_OFF32_LDFLAGS (LEGACY) | 15078 If sysconf(_SC_XBS5_ILP32_OFF32) returns -1, the meaning of this value is unspecified. 15079 Otherwise, this value is the set of final options to be given to the cc and c99 utilities to build | 15080 an application using a programming model with 32-bit int, long, pointer, and off_t types. | 15081 XSI _CS_XBS5_ILP32_OFF32_LIBS (LEGACY) | 15082 If sysconf(_SC_XBS5_ILP32_OFF32) returns -1, the meaning of this value is unspecified. 15083 Otherwise, this value is the set of libraries to be given to the cc and c99 utilities to build an | 15084 application using a programming model with 32-bit int, long, pointer, and off_t types. | 15085 XSI _CS_XBS5_ILP32_OFF32_LINTFLAGS (LEGACY) | 15086 If sysconf(_SC_XBS5_ILP32_OFF32) returns -1, the meaning of this value is unspecified. 15087 Otherwise, this value is the set of options to be given to the lint utility to check application 15088 source using a programming model with 32-bit int, long, pointer, and off_t types. | 15089 XSI _CS_XBS5_ILP32_OFFBIG_CFLAGS (LEGACY) | 15090 If sysconf(_SC_XBS5_ILP32_OFFBIG) returns -1, the meaning of this value is unspecified. 15091 Otherwise, this value is the set of initial options to be given to the cc and c99 utilities to | 15092 build an application using a programming model with 32-bit int, long, and pointer types, 15093 and an off_t type using at least 64 bits. | 15094 XSI _CS_XBS5_ILP32_OFFBIG_LDFLAGS (LEGACY) | 15095 If sysconf(_SC_XBS5_ILP32_OFFBIG) returns -1, the meaning of this value is unspecified. 15096 Otherwise, this value is the set of final options to be given to the cc and c99 utilities to build | 15097 an application using a programming model with 32-bit int, long, and pointer types, and an 15098 off_t type using at least 64 bits. | 15099 XSI _CS_XBS5_ILP32_OFFBIG_LIBS (LEGACY) | 15100 If sysconf(_SC_XBS5_ILP32_OFFBIG) returns -1, the meaning of this value is unspecified. 15101 Otherwise, this value is the set of libraries to be given to the cc and c99 utilities to build an | 15102 application using a programming model with 32-bit int, long, and pointer types, and an 15103 off_t type using at least 64 bits. | 15104 XSI _CS_XBS5_ILP32_OFFBIG_LINTFLAGS (LEGACY) | 15105 If sysconf(_SC_XBS5_ILP32_OFFBIG) returns -1, the meaning of this value is unspecified. 15106 Otherwise, this value is the set of options to be given to the lint utility to check an 15107 application using a programming model with 32-bit int, long, and pointer types, and an 15108 off_t type using at least 64 bits. | 15109 XSI _CS_XBS5_LP64_OFF64_CFLAGS (LEGACY) | 15110 If sysconf(_SC_XBS5_LP64_OFF64) returns -1, the meaning of this value is unspecified. 15111 Otherwise, this value is the set of initial options to be given to the cc and c99 utilities to | 15112 build an application using a programming model with 64-bit int, long, pointer, and off_t Base Definitions, Issue 6 447 Headers 15113 types. | 15114 XSI _CS_XBS5_LP64_OFF64_LDFLAGS (LEGACY) | 15115 If sysconf(_SC_XBS5_LP64_OFF64) returns -1, the meaning of this value is unspecified. 15116 Otherwise, this value is the set of final options to be given to the cc and c99 utilities to build | 15117 an application using a programming model with 64-bit int, long, pointer, and off_t types. | 15118 XSI _CS_XBS5_LP64_OFF64_LIBS (LEGACY) | 15119 If sysconf(_SC_XBS5_LP64_OFF64) returns -1, the meaning of this value is unspecified. 15120 Otherwise, this value is the set of libraries to be given to the cc and c99 utilities to build an | 15121 application using a programming model with 64-bit int, long, pointer, and off_t types. | 15122 XSI _CS_XBS5_LP64_OFF64_LINTFLAGS (LEGACY) | 15123 If sysconf(_SC_XBS5_LP64_OFF64) returns -1, the meaning of this value is unspecified. 15124 Otherwise, this value is the set of options to be given to the lint utility to check application 15125 source using a programming model with 64-bit int, long, pointer, and off_t types. | 15126 XSI _CS_XBS5_LPBIG_OFFBIG_CFLAGS (LEGACY) | 15127 If sysconf(_SC_XBS5_LPBIG_OFFBIG) returns -1, the meaning of this value is unspecified. 15128 Otherwise, this value is the set of initial options to be given to the cc and c99 utilities to | 15129 build an application using a programming model with an int type using at least 32 bits and 15130 long, pointer, and off_t types using at least 64 bits. | 15131 XSI _CS_XBS5_LPBIG_OFFBIG_LDFLAGS (LEGACY) | 15132 If sysconf(_SC_XBS5_LPBIG_OFFBIG) returns -1, the meaning of this value is unspecified. 15133 Otherwise, this value is the set of final options to be given to the cc and c99 utilities to build | 15134 an application using a programming model with an int type using at least 32 bits and long, 15135 pointer, and off_t types using at least 64 bits. | 15136 XSI _CS_XBS5_LPBIG_OFFBIG_LIBS (LEGACY) | 15137 If sysconf(_SC_XBS5_LPBIG_OFFBIG) returns -1, the meaning of this value is unspecified. 15138 Otherwise, this value is the set of libraries to be given to the cc and c99 utilities to build an | 15139 application using a programming model with an int type using at least 32 bits and long, 15140 pointer, and off_t types using at least 64 bits. | 15141 XSI _CS_XBS5_LPBIG_OFFBIG_LINTFLAGS (LEGACY) | 15142 If sysconf(_SC_XBS5_LPBIG_OFFBIG) returns -1, the meaning of this value is unspecified. 15143 Otherwise, this value is the set of options to be given to the lint utility to check application 15144 source using a programming model with an int type using at least 32 bits and long, pointer, 15145 and off_t types using at least 64 bits. 15146 The following symbolic constants shall be defined for the lseek( ) and fcntl( ) functions (they have 15147 distinct values): 15148 {SEEK_CUR} Set file offset to current plus offset. 15149 {SEEK_END} Set file offset to EOF plus offset. 15150 {SEEK_SET} Set file offset to offset. 15151 The following symbolic constants shall be defined for sysconf( ): 15152 _SC_2_C_BIND 15153 _SC_2_C_DEV 15154 _SC_2_C_VERSION 15155 _SC_2_FORT_DEV 15156 _SC_2_FORT_RUN 15157 _SC_2_LOCALEDEF 15158 _SC_2_PBS 448 Technical Standard (2000) (Draft July 28, 2000) Headers 15159 _SC_2_PBS_ACCOUNTING 15160 _SC_2_PBS_CHECKPOINT 15161 _SC_2_PBS_LOCATE 15162 _SC_2_PBS_MESSAGE 15163 _SC_2_PBS_TRACK 15164 _SC_2_SW_DEV 15165 _SC_2_UPE 15166 _SC_2_VERSION 15167 _SC_ARG_MAX 15168 _SC_AIO_LISTIO_MAX 15169 _SC_AIO_MAX 15170 _SC_AIO_PRIO_DELTA_MAX 15171 _SC_ASYNCHRONOUS_IO 15172 XSI _SC_ATEXIT_MAX 15173 BAR _SC_BARRIERS 15174 _SC_BASE 15175 _SC_BC_BASE_MAX 15176 _SC_BC_DIM_MAX 15177 _SC_BC_SCALE_MAX 15178 _SC_BC_STRING_MAX 15179 _SC_C_LANG_SUPPORT 15180 _SC_C_LANG_SUPPORT_R 15181 _SC_CHILD_MAX 15182 _SC_CLK_TCK 15183 CS _SC_CLOCK_SELECTION 15184 _SC_COLL_WEIGHTS_MAX 15185 _SC_DELAYTIMER_MAX 15186 _SC_DEVICE_IO 15187 _SC_DEVICE_SPECIFIC 15188 _SC_DEVICE_SPECIFIC_R 15189 _SC_EXPR_NEST_MAX 15190 _SC_FD_MGMT 15191 _SC_FIFO 15192 _SC_FILE_ATTRIBUTES 15193 _SC_FILE_LOCKING 15194 _SC_FILE_SYSTEM 15195 _SC_FSYNC 15196 _SC_GETGR_R_SIZE_MAX 15197 _SC_GETPW_R_SIZE_MAX 15198 XSI _SC_IOV_MAX 15199 _SC_JOB_CONTROL 15200 _SC_LINE_MAX 15201 _SC_LOGIN_NAME_MAX 15202 _SC_MAPPED_FILES 15203 _SC_MEMLOCK 15204 _SC_MEMLOCK_RANGE 15205 _SC_MEMORY_PROTECTION 15206 _SC_MESSAGE_PASSING 15207 MON _SC_MONOTONIC_CLOCK 15208 _SC_MQ_OPEN_MAX 15209 _SC_MQ_PRIO_MAX 15210 _SC_MULTIPLE_PROCESS Base Definitions, Issue 6 449 Headers 15211 _SC_NETWORKING 15212 _SC_NGROUPS_MAX 15213 _SC_OPEN_MAX 15214 XSI _SC_PAGE_SIZE 15215 _SC_PAGESIZE 15216 _SC_PIPE 15217 _SC_PRIORITIZED_IO 15218 _SC_PRIORITY_SCHEDULING 15219 _SC_RE_DUP_MAX 15220 THR _SC_READER_WRITER_LOCKS | 15221 _SC_REALTIME_SIGNALS 15222 _SC_REGEXP 15223 _SC_RTSIG_MAX 15224 _SC_SAVED_IDS 15225 _SC_SEMAPHORES 15226 _SC_SEM_NSEMS_MAX 15227 _SC_SEM_VALUE_MAX 15228 _SC_SHARED_MEMORY_OBJECTS 15229 _SC_SHELL 15230 _SC_SIGNALS 15231 _SC_SIGQUEUE_MAX 15232 _SC_SINGLE_PROCESS 15233 SPI _SC_SPIN_LOCKS 15234 _SC_STREAM_MAX 15235 _SC_SYNCHRONIZED_IO 15236 _SC_SYSTEM_DATABASE 15237 _SC_SYSTEM_DATABASE_R 15238 _SC_THREAD_ATTR_STACKADDR 15239 _SC_THREAD_ATTR_STACKSIZE 15240 _SC_THREAD_DESTRUCTOR_ITERATIONS 15241 _SC_THREAD_KEYS_MAX 15242 _SC_THREAD_PRIO_INHERIT 15243 _SC_THREAD_PRIO_PROTECT 15244 _SC_THREAD_PRIORITY_SCHEDULING 15245 _SC_THREAD_PROCESS_SHARED 15246 _SC_THREAD_SAFE_FUNCTIONS 15247 _SC_THREAD_STACK_MIN 15248 _SC_THREAD_THREADS_MAX 15249 _SC_THREADS 15250 _SC_TIMER_MAX 15251 _SC_TIMERS 15252 TRC _SC_TRACE | 15253 TEF _SC_TRACE_EVENT_FILTER | 15254 TRL _SC_TRACE_LOG | 15255 TRI _SC_TRACE_INHERIT | 15256 _SC_TTY_NAME_MAX | 15257 TYM _SC_TYPED_MEMORY_OBJECTS 15258 _SC_TZNAME_MAX 15259 _SC_USER_GROUPS 15260 _SC_USER_GROUPS_R 15261 _SC_V6_ILP32_OFF32 | 15262 _SC_V6_ILP32_OFFBIG | 450 Technical Standard (2000) (Draft July 28, 2000) Headers 15263 _SC_V6_LP64_OFF64 | 15264 _SC_V6_LPBIG_OFFBIG | 15265 _SC_VERSION | 15266 XSI _SC_XBS5_ILP32_OFF32 (LEGACY) | 15267 _SC_XBS5_ILP32_OFFBIG (LEGACY) | 15268 _SC_XBS5_LP64_OFF64 (LEGACY) | 15269 _SC_XBS5_LPBIG_OFFBIG (LEGACY) | 15270 _SC_XOPEN_CRYPT | 15271 _SC_XOPEN_ENH_I18N 15272 _SC_XOPEN_LEGACY 15273 _SC_XOPEN_REALTIME 15274 _SC_XOPEN_REALTIME_THREADS 15275 _SC_XOPEN_SHM 15276 _SC_XOPEN_STREAMS 15277 _SC_XOPEN_UNIX 15278 _SC_XOPEN_VERSION 15279 _SC_XOPEN_XCU_VERSION 15280 15281 The two constants _SC_PAGESIZE and _SC_PAGE_SIZE may be defined to have the same 15282 value. 15283 The following symbolic constants shall be defined as possible values for the function argument | 15284 to the lockf( ) function: 15285 F_LOCK Lock a section for exclusive use. 15286 F_TEST Test section for locks by other processes. 15287 F_TLOCK Test and lock a section for exclusive use. 15288 F_ULOCK Unlock locked sections. 15289 The following symbolic constants shall be defined for pathconf( ): | 15290 ADV _PC_ALLOC_SIZE_MIN 15291 AIO _PC_ASYNC_IO 15292 _PC_CHOWN_RESTRICTED 15293 _PC_FILESIZEBITS | 15294 _PC_LINK_MAX | 15295 _PC_MAX_CANON 15296 _PC_MAX_INPUT 15297 _PC_NAME_MAX 15298 _PC_NO_TRUNC 15299 _PC_PATH_MAX 15300 _PC_PIPE_BUF 15301 _PC_PRIO_IO 15302 ADV _PC_REC_INCR_XFER_SIZE 15303 _PC_REC_MAX_XFER_SIZE 15304 _PC_REC_MIN_XFER_SIZE 15305 _PC_REC_XFER_ALIGN 15306 _PC_SYNC_IO 15307 _PC_VDISABLE Base Definitions, Issue 6 451 Headers 15308 The following symbolic constants shall be defined for file streams: 15309 STDERR_FILENO File number of stderr; 2. 15310 STDIN_FILENO File number of stdin; 0. 15311 STDOUT_FILENO File number of stdout; 1. 15312 Type Definitions 15313 The size_t, ssize_t, uid_t, gid_t, off_t, and pid_t types shall be defined as described in | 15314 . | 15315 The useconds_t type shall be defined as described in . | 15316 The intptr_t type shall be defined as described in . | 15317 The socklen_t type shall be defined as described in . | 15318 Declarations 15319 The following shall be declared as functions and may also be defined as macros. Function 15320 prototypes shall be provided for use with an ISO C standard compiler. 15321 int access(const char *, int); 15322 unsigned alarm(unsigned); 15323 XSI int brk(void *); 15324 int chdir(const char *); 15325 int chown(const char *, uid_t, gid_t); 15326 int close(int); 15327 size_t confstr(int, char *, size_t); 15328 XSI char *crypt(const char *, const char *); 15329 char *ctermid(char *); 15330 int dup(int); 15331 int dup2(int, int); 15332 XSI void encrypt(char[64], int); 15333 int execl(const char *, const char *, ...); 15334 int execle(const char *, const char *, ...); 15335 int execlp(const char *, const char *, ...); 15336 int execv(const char *, char *const []); 15337 int execve(const char *, char *const [], char *const []); 15338 int execvp(const char *, char *const []); 15339 void _exit(int); 15340 XSI int fchown(int, uid_t, gid_t); 15341 int fchdir(int); 15342 SIO int fdatasync(int); 15343 pid_t fork(void); 15344 long fpathconf(int, int); 15345 int fsync(int); 15346 int ftruncate(int, off_t); 15347 char *getcwd(char *, size_t); 15348 gid_t getegid(void); 15349 uid_t geteuid(void); 15350 gid_t getgid(void); 15351 int getgroups(int, gid_t []); 15352 XSI long gethostid(void); 15353 int gethostname(char *, socklen_t); 452 Technical Standard (2000) (Draft July 28, 2000) Headers 15354 char *getlogin(void); 15355 int getlogin_r(char *, size_t); 15356 int getopt(int, char * const [], const char *); 15357 XSI pid_t getpgid(pid_t); 15358 pid_t getpgrp(void); 15359 pid_t getpid(void); 15360 pid_t getppid(void); 15361 XSI pid_t getsid(pid_t); 15362 uid_t getuid(void); 15363 XSI char *getwd(char *); (LEGACY) 15364 int isatty(int); 15365 XSI int lchown(const char *, uid_t, gid_t); 15366 int link(const char *, const char *); 15367 XSI int lockf(int, int, off_t); 15368 off_t lseek(int, off_t, int); 15369 XSI int nice(int); 15370 long pathconf(const char *, int); 15371 int pause(void); 15372 int pipe(int [2]); 15373 XSI ssize_t pread(int, void *, size_t, off_t); 15374 ssize_t pwrite(int, const void *, size_t, off_t); 15375 ssize_t read(int, void *, size_t); 15376 ssize_t readlink(const char *restrict, char *restrict, size_t); 15377 int rmdir(const char *); 15378 XSI void *sbrk(intptr_t); 15379 int setegid(gid_t); 15380 int seteuid(uid_t); 15381 int setgid(gid_t); 15382 int setpgid(pid_t, pid_t); 15383 XSI pid_t setpgrp(void); 15384 int setregid(gid_t, gid_t); 15385 int setreuid(uid_t, uid_t); 15386 pid_t setsid(void); 15387 int setuid(uid_t); 15388 unsigned sleep(unsigned); 15389 XSI void swab(const void *restrict, void *restrict, ssize_t); 15390 int symlink(const char *, const char *); 15391 void sync(void); 15392 long sysconf(int); 15393 pid_t tcgetpgrp(int); 15394 int tcsetpgrp(int, pid_t); 15395 XSI int truncate(const char *, off_t); 15396 char *ttyname(int); 15397 int ttyname_r(int, char *, size_t); 15398 XSI useconds_t ualarm(useconds_t, useconds_t); 15399 int unlink(const char *); 15400 XSI int usleep(useconds_t); 15401 pid_t vfork(void); 15402 ssize_t write(int, const void *, size_t); 15403 Implementations may also include the pthread_atfork( ) prototype as defined in (on 15404 page 322). Base Definitions, Issue 6 453 Headers 15405 The following external variables shall be declared: 15406 extern char *optarg; 15407 extern int optind, opterr, optopt; 15408 APPLICATION USAGE 15409 None. 15410 RATIONALE 15411 As IEEE Std. 1003.1-200x evolved, certain options became sufficiently standardized that it was | 15412 concluded that simply requiring one of the option choices was simpler than retaining the option. | 15413 However, for backwards compatibility, the option flags (with required constant values) are | 15414 retained. | 15415 Version Test Macros 15416 The standard developers considered altering the definition of _POSIX_VERSION and removing 15417 _SC_VERSION from the specification of sysconf( ) since the utility to an application was deemed 15418 by some to be minimal, and since the implementation of the functionality is potentially 15419 problematic. 15420 Applications are allowed the ability to adapt to various versions of IEEE Std. 1003.1-200x at 15421 compile time by conditionally compiling different code depending on the value of 15422 _POSIX_VERSION. For example, an application which expects the semantics of the 15423 POSIX.1-1988 standard cuserid( ) but also wishes to compile and run on a system which 15424 conforms to the POSIX.1-1990 standard might be coded as in the following program fragment: 15425 #if _POSIX_VERSION == 198808L 15426 val = cuserid(); 15427 #else 15428 { 15429 struct passwd *pwp; 15430 pwp = getpwuid(geteuid()); 15431 val = pwp->pw_name; 15432 } 15433 #endif 15434 While POSIX does not make any attempt to define application binary interaction with the 15435 underlying operating system, the standard developers recognized that support for existing 15436 application binaries is a concern to manufacturers, application developers, and the users of 15437 implementations conforming to IEEE Std. 1003.1-200x. To that end, an application can query 15438 _SC_VERSION at runtime via sysconf( ) to determine whether the current version of the 15439 operating system supports the necessary functionality as in the following program fragment: 15440 if(sysconf(_SC_VERSION) != 200xxxL) { 15441 fprintf(stderr, "POSIX.1-1990 system required, terminating\n") 15442 exit(1); 15443 } 15444 While the above example does not provide the greatest degree of imaginable utility to the 15445 application developer or user, it is arguably better than a core dump or some other equally 15446 obscure result. (It is also possible for implementations to encode and recognize application | 15447 binaries compiled in various POSIX.1-conforming environments, and modify the semantics of | 15448 the underlying system to conform to the expectations of the application.) For the reasons 15449 outlined in the preceding paragraphs, the standard developers elected to retain the 15450 _POSIX_VERSION and _SC_VERSION functionality. 454 Technical Standard (2000) (Draft July 28, 2000) Headers 15451 Compile-Time Symbolic Constants for System-Wide Options 15452 IEEE Std. 1003.1-200x now includes support in certain areas for the newly adopted policy 15453 governing options and stubs. 15454 This policy provides flexibility for implementations in how they support options. It also 15455 specifies how conforming applications can adapt to different implementations that support 15456 different sets of options. It allows the following: 15457 1. If an implementation has no interest in supporting an option, it does not have to provide 15458 anything associated with that option beyond the announcement that it does not support it. 15459 2. An implementation can support a partial or incompatible version of an option (as a non- 15460 standard extension) as long as it does not claim to support the option. 15461 3. An application can determine whether the option is supported. A strictly conforming 15462 application must check this announcement mechanism before first using anything 15463 associated with the option. 15464 There is an important implication of this policy. IEEE Std. 1003.1-200x cannot dictate the 15465 behavior of interfaces associated with an option when the implementation does not claim to 15466 support the option. In particular, it cannot require that a function associated with an 15467 unsupported option will fail if it does not perform as specified. However, this policy does not 15468 prevent a standard from requiring certain functions to always be present, but that they shall 15469 always fail on some implementations. The setpgid( ) function in the POSIX.1-1990 standard, for 15470 example, is considered appropriate. 15471 The POSIX standards include various options, and the C language binding support for an option 15472 implies that the implementation must supply data types and function interfaces. An application 15473 must be able to discover whether the implementation supports each option. 15474 Any application must consider the following three cases for each option: 15475 1. Option never supported. 15476 The implementation advertises at compile time that the option will never be supported. In 15477 this case, it is not necessary for the implementation to supply any of the data types or 15478 function interfaces that are provided only as part of the option. The implementation might 15479 provide data types and functions that are similar to those defined by IEEE Std. 1003.1-200x, 15480 but there is no guarantee for any particular behavior. 15481 2. Option always supported. 15482 The implementation advertises at compile time that the option will always be supported. 15483 In this case, all data types and function interfaces shall be available and shall operate as 15484 specified. 15485 3. Option might or might not be supported. 15486 Some implementations might not provide a mechanism to specify support of options at 15487 compile time. In addition, the implementation might be unable or unwilling to specify 15488 support or non-support at compile time. In either case, any application that might use the 15489 option at runtime must be able to compile and execute. The implementation must provide, 15490 at compile time, all data types and function interfaces that are necessary to allow this. In 15491 this situation, there must be a mechanism that allows the application to query, at runtime, 15492 whether the option is supported. If the application attempts to use the option when it is 15493 not supported, the result is unspecified unless explicitly specified otherwise in 15494 IEEE Std. 1003.1-200x. Base Definitions, Issue 6 455 Headers 15495 FUTURE DIRECTIONS 15496 None. 15497 SEE ALSO 15498 , , , , , the System Interfaces | 15499 volume of IEEE Std. 1003.1-200x, access( ), alarm( ), chdir( ), chown( ), close( ), crypt( ), ctermid( ), 15500 dup( ), encrypt( ), environ( ), exec( ), exit( ), fchdir( ), fchown( ), fcntl( ), fork( ), fpathconf( ), fsync( ), 15501 ftruncate( ), getcwd( ), getegid( ), geteuid( ), getgid( ), getgroups( ), gethostid( ), gethostname( ), 15502 getlogin( ), getpgid( ), getpgrp( ), getpid( ), getppid( ), getsid( ), getuid( ), isatty( ), lchown( ), link( ), | 15503 lockf( ), lseek( ), nice( ), pathconf( ), pause( ), pipe( ), read( ), readlink( ), rmdir( ), setgid( ), setpgid( ), 15504 setpgrp( ), setregid( ), setreuid( ), setsid( ), setuid( ), sleep( ), swab( ), symlink( ), sync( ), sysconf( ), 15505 tcgetpgrp( ), tcsetpgrp( ), truncate( ), ttyname( ), ualarm( ), unlink( ), usleep( ), vfork( ), write( ) 15506 CHANGE HISTORY 15507 First released in Issue 1. Derived from Issue 1 of the SVID. | 15508 Issue 4 15509 The symbolic constants F_ULOCK, F_LOCK, F_TLOCK, F_TEST, GF_PATH, IF_PATH, and 15510 PF_PATH are withdrawn. 15511 The required value of _XOPEN_VERSION is defined and the constant is marked as an extension. 15512 The constants _XOPEN_XPG2, _XOPEN_XPG3, and _XOPEN_XPG4 are added. 15513 The constants _POSIX2_* are added. 15514 Reference to the header is added for the definitions of size_t, ssize_t, uid_t, gid_t, 15515 off_t, and pid_t. These are marked as extensions. 15516 The names chroot( ), crypt( ), encrypt( ), fsync( ), getopt( ), getpass( ), nice( ), and swab( ) are added to 15517 the list of functions declared in this header. With the exception of getopt( ), these are all marked 15518 as extensions. 15519 The APPLICATION USAGE section is removed. 15520 The following changes are incorporated for alignment with the ISO POSIX-1 standard and the 15521 ISO POSIX-2 standard: 15522 * The function declarations in this header are expanded to full ISO C standard prototypes. 15523 * A large number of new constants are defined for the sysconf( ) function, including all those 15524 with prefixes _SC_2 and _SC_BC, plus: 15525 _SC_COLL_WEIGHTS_MAX 15526 _SC_EXPR_NEST_MAX 15527 _SC_LINE_MAX 15528 _SC_RE_DUP_MAX 15529 _SC_STREAM_MAX 15530 _SC_TZNAME_MAX 15531 * The confstr( ) function is added to the list of functions declared in this header, complete with 15532 a new set of constants for alignment with the ISO POSIX-2 standard. 15533 The following change is incorporated for alignment with the FIPS requirements: 15534 * The following symbolic constants are always defined: 456 Technical Standard (2000) (Draft July 28, 2000) Headers 15535 _POSIX_CHOWN_RESTRICTED 15536 _POSIX_NO_TRUNC 15537 _POSIX_VDISABLE 15538 _POSIX_SAVED_IDS 15539 _POSIX_JOB_CONTROL 15540 In Issue 3, they are only defined if the associated option is present. 15541 Issue 4, Version 2 15542 The following changes are incorporated for X/OPEN UNIX conformance: 15543 * The Option Group constant _XOPEN_UNIX is defined. 15544 * The sysconf( ) symbolic constants _SC_ATEXIT_MAX, _SC_IOV_MAX, _SC_PAGESIZE, and 15545 _SC_PAGE_SIZE are defined. 15546 * The brk( ), fchown( ), fchdir( ), ftruncate( ), gethostid( ), getpagesize( ), getpgid( ), getsid( ), getwd( ), 15547 lchown( ), lockf( ), readlink( ), sbrk( ), setpgrp( ), setregid( ), setreuid( ), symlink( ), sync( ), 15548 truncate( ), ualarm( ), usleep( ), and , vfork( ) functions are added to the list of functions 15549 declared in this header. 15550 * The symbolic constants F_ULOCK, F_LOCK, F_TLOCK, and F_TEST are added. 15551 Issue 5 15552 The DESCRIPTION is updated for alignment with the POSIX Realtime Extension and the POSIX 15553 Threads Extension. 15554 The symbolic constants _XOPEN_REALTIME and _XOPEN_REALTIME_THREADS are added. 15555 _POSIX2_C_BIND, _XOPEN_ENH_I18N, and _XOPEN_SHM must now be set to a value other 15556 than -1 by a conforming implementation. 15557 Large File System extensions are added. 15558 The type of the argument to sbrk( ) is changed from int to intptr_t. 15559 _XBS_ constants are added to the list of constants for Options and Option Groups, to the list of 15560 constants for the confstr( ) function, and to the list of constants to the sysconf( ) function. These 15561 are all marked EX. 15562 Issue 6 15563 _POSIX2_C_VERSION is removed. 15564 The Open Group corrigenda item U026/4 has been applied, adding the prototype for fdatasync( ). 15565 The Open Group corrigenda item U026/1 has been applied, adding the symbols 15566 _SC_XOPEN_LEGACY, _SC_XOPEN_REALTIME, and _SC_XOPEN_REALTIME_THREADS. 15567 The symbols _XOPEN_STREAMS and _SC_XOPEN_STREAMS are added to support the XSI 15568 STREAMS Option Group. 15569 Constants for profiling options are added. 15570 Text in the DESCRIPTION relating to conformance requirements is moved elsewhere in 15571 IEEE Std. 1003.1-200x. 15572 The legacy symbol _SC_PASS_MAX is removed. 15573 The following new requirements on POSIX implementations derive from alignment with the 15574 Single UNIX Specification: 15575 * The _CS_XBS5_* constants are added for the confstr( ) function. Base Definitions, Issue 6 457 Headers 15576 * The _SC_XBS5_* constants are added for the sysconf( ) function. 15577 * The symbolic constants F_ULOCK, F_LOCK, F_TLOCK, and F_TEST are added. 15578 * The uid_t, gid_t, off_t, pid_t, and useconds_t types are mandated. 15579 The gethostname( ) prototype is added for sockets. 15580 New section added for System Wide Options. 15581 Function prototypes for setegid( ) and seteuid( ) are added. 15582 Option symbolic constants are added for _POSIX_ADVISORY_INFO, _POSIX_CPUTIME, 15583 _POSIX_SPAWN, _POSIX_SPORADIC_SERVER, _POSIX_THREAD_CPUTIME, 15584 _POSIX_THREAD_SPORADIC_SERVER, and _POSIX_TIMEOUTS, and pathconf( ) variables are 15585 added for _PC_ALLOC_SIZE_MIN, _PC_REC_INCR_XFER_SIZE, _PC_REC_MAX_XFER_SIZE, 15586 _PC_REC_MIN_XFER_SIZE, and _PC_REC_XFER_ALIGN for alignment with 15587 IEEE Std. 1003.1d-1999. 15588 The following are added for alignment with IEEE Std. 1003.1j-2000: 15589 * Option symbolic constants _POSIX_BARRIERS, _POSIX_CLOCK_SELECTION, 15590 _POSIX_MONOTONIC_CLOCK, _POSIX_READER_WRITER_LOCKS, 15591 _POSIX_SPIN_LOCKS, and _POSIX_TYPED_MEMORY_OBJECTS 15592 * sysconf( ) variables _SC_BARRIERS, _SC_CLOCK_SELECTION, 15593 _SC_MONOTONIC_CLOCK, _SC_READER_WRITER_LOCKS, _SC_SPIN_LOCKS, and 15594 _SC_TYPED_MEMORY_OBJECTS 15595 The _SC_XBS5 macros associated with the ISO/IEC 9899: 1990 standard are marked LEGACY, | 15596 and new equivalent _SC_V6 macros associated with the ISO/IEC 9899: 1999 standard are | 15597 introduced. | 15598 The getwd( ) function is marked LEGACY. | 15599 The restrict keyword is added to the prototypes for realink( ) and swab( ). | 15600 Constants for options are now harmonized, so when supported they take the year of approval of | 15601 IEEE Std. 1003.1-200x as the value. | 15602 The following are added for alignment with IEEE Std. 1003.1q-2000: | 15603 * Optional symbolic constants _POSIX_TRACE, _POSIX_TRACE_EVENT_FILTER, | 15604 _POSIX_TRACE_LOG, and _POSIX_TRACE_INHERIT | 15605 * The sysconf( ) symbolic constants _SC_TRACE, _SC_TRACE_EVENT_FILTER, || 15606 _SC_TRACE_LOG, and _SC_TRACE_INHERIT. | 458 Technical Standard (2000) (Draft July 28, 2000) Headers 15607 NAME 15608 utime.h - access and modification times structure 15609 SYNOPSIS 15610 #include 15611 DESCRIPTION 15612 The header shall declare the structure utimbuf, which shall include the following 15613 members: 15614 time_t actime Access time. 15615 time_t modtime Modification time. 15616 The times shall be measured in seconds since the Epoch. 15617 The type time_t shall be defined as described in . | 15618 The following shall be declared as a function and may also be defined as a macro. Function 15619 prototypes shall be provided for use with an ISO C standard compiler. 15620 int utime(const char *, const struct utimbuf *); 15621 APPLICATION USAGE 15622 None. 15623 RATIONALE 15624 None. 15625 FUTURE DIRECTIONS 15626 None. 15627 SEE ALSO 15628 , the System Interfaces volume of IEEE Std. 1003.1-200x, utime( ) 15629 CHANGE HISTORY 15630 First released in Issue 3. 15631 Issue 4 15632 Reference to the header is added for the definition of time_t. This is marked as an 15633 extension. 15634 The following change is incorporated for alignment with the ISO POSIX-1 standard: 15635 * The function declarations in this header are expanded to full ISO C standard prototypes. 15636 Issue 6 15637 The following new requirements on POSIX implementations derive from alignment with the 15638 Single UNIX Specification: 15639 * The time_t type is defined. Base Definitions, Issue 6 459 Headers 15640 NAME 15641 utmpx.h - user accounting database definitions 15642 SYNOPSIS 15643 XSI #include 15644 15645 DESCRIPTION 15646 The header shall define the utmpx structure that shall include at least the following 15647 members: 15648 char ut_user[] User login name. 15649 char ut_id[] Unspecified initialization process identifier. 15650 char ut_line[] Device name. 15651 pid_t ut_pid Process ID. 15652 short ut_type Type of entry. 15653 struct timeval ut_tv Time entry was made. 15654 The pid_t type shall be defined through typedef as described in . 15655 The timeval structure shall be defined as described in . 15656 Inclusion of the header may also make visible all symbols from . 15657 The following symbolic constants shall be defined as possible values for the ut_type member of 15658 the utmpx structure: 15659 EMPTY No valid user accounting information. 15660 BOOT_TIME Identifies time of system boot. 15661 OLD_TIME Identifies time when system clock changed. 15662 NEW_TIME Identifies time after system clock changed. 15663 USER_PROCESS Identifies a process. 15664 INIT_PROCESS Identifies a process spawned by the init process. 15665 LOGIN_PROCESS Identifies the session leader of a logged in user. 15666 DEAD_PROCESS Identifies a session leader who has exited. 15667 The following shall be declared as functions and may also be defined as macros. Function 15668 prototypes shall be provided for use with an ISO C standard compiler. 15669 void endutxent(void); 15670 struct utmpx *getutxent(void); 15671 struct utmpx *getutxid(const struct utmpx *); 15672 struct utmpx *getutxline(const struct utmpx *); 15673 struct utmpx *pututxline(const struct utmpx *); 15674 void setutxent(void); 460 Technical Standard (2000) (Draft July 28, 2000) Headers 15675 APPLICATION USAGE 15676 None. 15677 RATIONALE 15678 None. 15679 FUTURE DIRECTIONS 15680 None. 15681 SEE ALSO 15682 , , the System Interfaces volume of IEEE Std. 1003.1-200x, endutxent( ) 15683 CHANGE HISTORY 15684 First released in Issue 4, Version 2. Base Definitions, Issue 6 461 Headers 15685 NAME 15686 wchar.h - wide-character types 15687 SYNOPSIS 15688 #include 15689 DESCRIPTION 15690 CX The functionality described on this reference page extends the ISO C standard. Applications 15691 shall define the appropriate feature test macro (see the System Interfaces volume of 15692 IEEE Std. 1003.1-200x, Section 2.2, The Compilation Environment) to enable the visibility of 15693 symbols in this header. 15694 The header shall define the following data types through typedef: 15695 wchar_t As described in . 15696 wint_t An integer type capable of storing any valid value of wchar_t or WEOF. | 15697 wctype_t A scalar type of a data object that can hold values which represent locale- 15698 specific character classification. 15699 mbstate_t An object type other than an array type that can hold the conversion state 15700 information necessary to convert between sequences of (possibly multibyte) 15701 XSI characters and wide characters. If a codeset is being used such that an 15702 mbstate_t needs to preserve more than 2 levels of reserved state, the results 15703 are unspecified. 15704 XSI FILE As described in . 15705 size_t As described in . 15706 The header shall declare the following as functions and may also define them as 15707 macros. Function prototypes shall be provided for use with an ISO C standard compiler. 15708 wint_t btowc(int); 15709 wint_t fgetwc(FILE *); 15710 wchar_t *fgetws(wchar_t *restrict, int, FILE *restrict); 15711 wint_t fputwc(wchar_t, FILE *); 15712 int fputws(const wchar_t *restrict, FILE *restrict); 15713 int fwide(FILE *, int); 15714 int fwprintf(FILE *restrict, const wchar_t *restrict, ...); 15715 int fwscanf(FILE *restrict, const wchar_t *restrict, ...); 15716 wint_t getwc(FILE *); 15717 wint_t getwchar(void); 15718 int iswalnum(wint_t); 15719 int iswalpha(wint_t); 15720 int iswcntrl(wint_t); 15721 int iswctype(wint_t, wctype_t); 15722 int iswdigit(wint_t); 15723 int iswgraph(wint_t); 15724 int iswlower(wint_t); 15725 int iswprint(wint_t); 15726 int iswpunct(wint_t); 15727 int iswspace(wint_t); 15728 int iswupper(wint_t); 15729 int iswxdigit(wint_t); 15730 size_t mbrlen(const char *restrict, size_t, mbstate_t *restrict); 15731 size_t mbrtowc(wchar_t *restrict, const char *restrict, size_t, 462 Technical Standard (2000) (Draft July 28, 2000) Headers 15732 mbstate_t *restrict); 15733 int mbsinit(const mbstate_t *); 15734 size_t mbsrtowcs(wchar_t *restrict, const char **restrict, size_t, 15735 mbstate_t *restrict); 15736 wint_t putwc(wchar_t, FILE *); 15737 wint_t putwchar(wchar_t); 15738 int swprintf(wchar_t *restrict, size_t, 15739 const wchar_t *restrict, ...); 15740 int swscanf(const wchar_t *restrict, 15741 const wchar_t *restrict, ...); 15742 wint_t towlower(wint_t); 15743 wint_t towupper(wint_t); 15744 wint_t ungetwc(wint_t, FILE *); 15745 int vfwprintf(FILE *restrict, const wchar_t *restrict, va_list); 15746 int vfwscanf(FILE *restrict, const wchar_t *restrict, va_list); 15747 int vwprintf(const wchar_t *restrict, va_list); 15748 int vswprintf(wchar_t *restrict, size_t, 15749 const wchar_t *restrict, va_list); 15750 int vswscanf(const wchar_t *restrict, const wchar_t *restrict, 15751 va_list); 15752 int vwscanf(const wchar_t *restrict, va_list); 15753 size_t wcrtomb(char *restrict, wchar_t, mbstate_t *restrict); 15754 wchar_t *wcscat(wchar_t *restrict, const wchar_t *restrict); 15755 wchar_t *wcschr(const wchar_t *, wchar_t); 15756 int wcscmp(const wchar_t *, const wchar_t *); 15757 int wcscoll(const wchar_t *, const wchar_t *); 15758 wchar_t *wcscpy(wchar_t *restrict, const wchar_t *restrict); 15759 size_t wcscspn(const wchar_t *, const wchar_t *); 15760 size_t wcsftime(wchar_t *restrict, size_t, 15761 const wchar_t *restrict, const struct tm *restrict); 15762 size_t wcslen(const wchar_t *); 15763 wchar_t *wcsncat(wchar_t *restrict, const wchar_t *restrict, size_t); 15764 int wcsncmp(const wchar_t *, const wchar_t *, size_t); 15765 wchar_t *wcsncpy(wchar_t *restrict, const wchar_t *restrict, size_t); 15766 wchar_t *wcspbrk(const wchar_t *, const wchar_t *); 15767 wchar_t *wcsrchr(const wchar_t *, wchar_t); 15768 size_t wcsrtombs(char *restrict, const wchar_t **restrict, 15769 size_t, mbstate_t *restrict); 15770 size_t wcsspn(const wchar_t *, const wchar_t *); 15771 wchar_t *wcsstr(const wchar_t *restrict, const wchar_t *restrict); 15772 double wcstod(const wchar_t *restrict, wchar_t **restrict); 15773 float wcstof(const wchar_t *restrict, wchar_t **restrict); 15774 wchar_t *wcstok(wchar_t *restrict, const wchar_t *restrict, 15775 wchar_t **restrict); 15776 long wcstol(const wchar_t *restrict, wchar_t **restrict, int); 15777 long double wcstold(const wchar_t *restrict, wchar_t **restrict); 15778 long long wcstoll(const wchar_t *restrict, wchar_t **restrict, int); 15779 unsigned long wcstoul(const wchar_t *restrict, wchar_t **restrict, int); 15780 unsigned long long 15781 wcstoull(const wchar_t *restrict, wchar_t **restrict, int); 15782 XSI wchar_t *wcswcs(const wchar_t *, const wchar_t *); 15783 int wcswidth(const wchar_t *, size_t); Base Definitions, Issue 6 463 Headers 15784 size_t wcsxfrm(wchar_t *restrict, const wchar_t *restrict, size_t); 15785 int wctob(wint_t); 15786 wctype_t wctype(const char *); 15787 XSI int wcwidth(wchar_t); 15788 wchar_t *wmemchr(const wchar_t *, wchar_t, size_t); 15789 int wmemcmp(const wchar_t *, const wchar_t *, size_t); 15790 wchar_t *wmemcpy(wchar_t *restrict, const wchar_t *restrict, size_t); 15791 wchar_t *wmemmove(wchar_t *, const wchar_t *, size_t); 15792 wchar_t *wmemset(wchar_t *, wchar_t, size_t); 15793 int wprintf(const wchar_t *restrict, ...); 15794 int wscanf(const wchar_t *restrict, ...); 15795 The header shall define the following macro names: 15796 WCHAR_MAX The maximum value representable by an object of type wchar_t. 15797 WCHAR_MIN The minimum value representable by an object of type wchar_t. 15798 WEOF Constant expression of type wint_t that is returned by several WP functions 15799 to indicate end-of-file. 15800 NULL As described in . 15801 The tag tm shall be declared as naming an incomplete structure type, the contents of which are 15802 described in the header . 15803 Inclusion of the header may make visible all symbols from the headers , 15804 , , , , , and . 15805 APPLICATION USAGE 15806 None. 15807 RATIONALE 15808 None. 15809 FUTURE DIRECTIONS 15810 None. 15811 SEE ALSO 15812 , , , , , , , the System 15813 Interfaces volume of IEEE Std. 1003.1-200x, btowc( ), fgetwc( ), fgetws( ), fputwc( ), fputws( ), | 15814 fwide( ), fwprintf( ), fwscanf( ), getwc( ), getwchar( ), iswalnum( ), iswalpha( ), iswcntrl( ), iswctype( ), | 15815 iswdigit( ), iswgraph( ), iswlower( ), iswprint( ), iswpunct( ), iswspace( ), iswupper( ), iswxdigit( ), 15816 iswctype( ), mbsinit( ), mbrlen( ), mbrtowc( ), mbsrtowcs( ), putwc( ), putwchar( ), swprintf( ), swscanf( ), | 15817 towlower( ), towupper( ), ungetwc( ), vfwprintf( ), vfwscanf( ), vswprintf( ), vswscanf( ), vwscanf( ), | 15818 wcrtomb( ), wcsrtombs( ), wcscat( ), wcschr( ), wcscmp( ), wcscoll( ), wcscpy( ), wcscspn( ), wcsftime( ), 15819 wcslen( ), wcsncat( ), wcsncmp( ), wcsncpy( ), wcspbrk( ), wcsrchr( ), wcsspn( ), wcsstr( ), wcstod( ), | 15820 wcstof( ), wcstok( ), wcstol( ), wcstold( ), wcstoll( ), wcstoul( ), wcstoull( ), wcswcs( ), wcswidth( ), | 15821 wcsxfrm( ), wctob( ), wctype( ), wcwidth( ), wmemchr( ), wmemcmp( ), wmemcpy( ), wmemmove( ), 15822 wmemset( ), wprintf( ), wscanf( ) 15823 CHANGE HISTORY 15824 First released in Issue 4. 15825 Issue 5 15826 Aligned with the ISO/IEC 9899: 1990/Amendment 1: 1995 (E). 464 Technical Standard (2000) (Draft July 28, 2000) Headers 15827 Issue 6 15828 The Open Group corrigenda item U021/10 has been applied. The prototypes for wcswidth( ) and 15829 wcwidth( ) are marked as extensions. 15830 The Open Group corrigenda item U028/5 has been applied, correcting the prototype for the 15831 mbsinit( ) function. | 15832 The following changes are made for alignment with the ISO/IEC 9899: 1999 standard: | 15833 * Various function prototypes are updated to add the restrict keyword. || 15834 * The functions vfwscanf( ), vswscanf( ), wcstof( ), wcstold( ), wcstoll( ), and wcstoull( ) are added. | Base Definitions, Issue 6 465 Headers 15835 NAME 15836 wctype.h - wide-character classification and mapping utilities 15837 SYNOPSIS 15838 #include 15839 DESCRIPTION 15840 CX The functionality described on this reference page extends the ISO C standard. Applications 15841 shall define the appropriate feature test macro (see the System Interfaces volume of 15842 IEEE Std. 1003.1-200x, Section 2.2, The Compilation Environment) to enable the visibility of 15843 symbols in this header. 15844 The header shall define the following data types through typedef: 15845 wint_t As described in . 15846 wctrans_t A scalar type that can hold values which represent locale-specific character 15847 mappings. 15848 wctype_t As described in . 15849 The header shall declare the following as functions and may also define them as 15850 macros. Function prototypes shall be provided for use with an ISO C standard compiler. 15851 int iswalnum(wint_t); 15852 int iswalpha(wint_t); 15853 int iswblank(wint_t); 15854 int iswcntrl(wint_t); 15855 int iswdigit(wint_t); 15856 int iswgraph(wint_t); 15857 int iswlower(wint_t); 15858 int iswprint(wint_t); 15859 int iswpunct(wint_t); 15860 int iswspace(wint_t); 15861 int iswupper(wint_t); 15862 int iswxdigit(wint_t); 15863 int iswctype(wint_t, wctype_t); 15864 wint_t towctrans(wint_t, wctrans_t); 15865 wint_t towlower(wint_t); 15866 wint_t towupper(wint_t); 15867 wctrans_t wctrans(const char *); 15868 wctype_t wctype(const char *); 15869 The header shall define the following macro name: 15870 WEOF Constant expression of type wint_t that is returned by several MSE functions 15871 to indicate end-of-file. 15872 For all functions described in this header that accept an argument of type wint_t, the value is 15873 representable as a wchar_t or equals the value of WEOF. If this argument has any other value, 15874 the behavior is undefined. 15875 The behavior of these functions shall be affected by the LC_CTYPE category of the current locale. 15876 Inclusion of the header may make visible all symbols from the headers , 15877 , , , , , , and . 466 Technical Standard (2000) (Draft July 28, 2000) Headers 15878 APPLICATION USAGE 15879 None. 15880 RATIONALE 15881 None. 15882 FUTURE DIRECTIONS 15883 None. 15884 SEE ALSO 15885 , , the System Interfaces volume of IEEE Std. 1003.1-200x, iswalnum( ), 15886 iswalpha( ), iswblank( ), iswcntrl( ), iswctype( ), iswdigit( ), iswgraph( ), iswlower( ), iswprint( ), | 15887 iswpunct( ), iswspace( ), iswupper( ), iswxdigit( ), setlocale( ), towctrans( ), towlower( ), towupper( ), 15888 wctrans( ), wctype( ) 15889 CHANGE HISTORY 15890 First released in Issue 5. Derived from the ISO/IEC 9899: 1990/Amendment 1: 1995 (E). | 15891 Issue 6 | 15892 The iswblank( ) function is added for alignment with the ISO/IEC 9899: 1999 standard. | Base Definitions, Issue 6 467 Headers 15893 NAME 15894 wordexp.h - word-expansion types 15895 SYNOPSIS 15896 #include 15897 DESCRIPTION 15898 The header shall define the structures and symbolic constants used by the 15899 wordexp( ) and wordfree( ) functions. 15900 The structure type wordexp_t shall contain at least the following members: 15901 size_t we_wordc Count of words matched by words. 15902 char **we_wordv Pointer to list of expanded words. 15903 size_t we_offs Slots to reserve at the beginning of we_wordv. 15904 The flags argument to the wordexp( ) function shall be the bitwise-inclusive OR of the following 15905 flags: 15906 WRDE_APPEND Append words to those previously generated. 15907 WRDE_DOOFFS Number of null pointers to prepend to we_wordv. 15908 WRDE_NOCMD Fail if command substitution is requested. 15909 WRDE_REUSE The pwordexp argument was passed to a previous successful call to 15910 wordexp( ), and has not been passed to wordfree( ). The result is the same 15911 as if the application had called wordfree( ) and then called wordexp( ) 15912 without WRDE_REUSE. 15913 WRDE_SHOWERR Do not redirect stderr to /dev/null. 15914 WRDE_UNDEF Report error on an attempt to expand an undefined shell variable. 15915 The following constants shall be defined as error return values: 15916 WRDE_BADCHAR One of the unquoted characters-, '|', '&', ';', '<', '>', 15917 '(', ')', '{', '}'-appears in words in an inappropriate context. 15918 WRDE_BADVAL Reference to undefined shell variable when WRDE_UNDEF is set in flags. 15919 WRDE_CMDSUB Command substitution requested when WRDE_NOCMD was set in flags. 15920 WRDE_NOSPACE Attempt to allocate memory failed. 15921 WRDE_NOSYS The implementation does not support the function. 15922 WRDE_SYNTAX Shell syntax error, such as unbalanced parentheses or unterminated 15923 string. 15924 The following shall be declared as functions and may also be declared as macros. Function 15925 prototypes shall be provided for use with an ISO C standard compiler. 15926 int wordexp(const char *restrict, wordexp_t *restrict, int); 15927 void wordfree(wordexp_t *); 15928 The implementation may define additional macros or constants using names beginning with 15929 WRDE_. 468 Technical Standard (2000) (Draft July 28, 2000) Headers 15930 APPLICATION USAGE 15931 None. 15932 RATIONALE 15933 None. 15934 FUTURE DIRECTIONS 15935 None. 15936 SEE ALSO 15937 The System Interfaces volume of IEEE Std. 1003.1-200x, wordexp( ), the Shell and Utilities volume | 15938 of IEEE Std. 1003.1-200x | 15939 CHANGE HISTORY 15940 First released in Issue 4. Derived from the ISO POSIX-2 standard. | 15941 Issue 6 | 15942 The restrict keyword is added to the prototype for wordexp( ). | Base Definitions, Issue 6 469 Headers 470 Technical Standard (2000) (Draft July 28, 2000) 1 Index 2 (time) resolution .......................................................96 .....................................................................320 3 / .................................................................................211 .............................................................322 4 /dev ...........................................................................211 ...................................................................327 5 /dev/console...........................................................211 ..................................................................329 6 /dev/null..................................................................211 .................................................................331 7 /dev/tty ...................................................................211 ................................................................333 8 /tmp..........................................................................211 .......................................................335 9 ......................................................................232 ...............................................................336 10 .........................................................................42 .................................................................338 11 ..........................................................234 .....................................................................101 12 .................................................................235 ...............................................................346 13 ..............................................................47 ................................................................348 14 .......................................................................53 ..............................................................350 15 ......................................................56 ................................................................351 16 ............................................................236 .................................................................352 17 ....................................................................240 ...................................................................358 18 ..................................................................242 .................................................................362 19 .................................................................244 .................................................................366 20 ..................................................................246 ...............................................................368 21 ..................................................................247 ...............................................................369 22 ...................................................................251 ..............................................................244 23 ....................................................................254 ..............................................................374 24 ...................................................................259 ........................................................376 25 .............................................................263 ............................................................379 26 ............................................................265 ....................................................381 27 ...............................................................73 .........................................................383 28 .....................................................................266 ............................................................385 29 ....................................................................268 ............................................................387 30 .....................................................................270 ........................................................389 31 ..................................................................272 .............................................................394 32 .............................................................273 .......................................................399 33 ................................................................276 ...........................................................401 34 ............................................................277 .........................................................403 35 ................................................................280 .........................................................404 36 .................................................................281 .........................................................405 37 .................................................................296 ..............................................................408 38 ..................................................................298 ...............................................................409 39 ..........................................................305 ....................................................410 40 .............................................................306 ...........................................................411 41 .................................................................308 ................................................................413 42 .................................................................309 .........................................................................107 43 .................................................................310 .......................................................................415 44 .........................................................314 ..............................................................417 45 .......................................................318 ..............................................................423 46 ...................................................................82 ...................................................................427 47 ............................................................319 ...................................................................431 Base Definitions, Issue 6 471 Index 48 ............................................................435 _POSIX2_LOCALEDEF ................................437, 442 49 .................................................................436 _POSIX2_PBS ..........................................................442 50 ................................................................437 _POSIX2_PBS_ACCOUNTING ..........................442 51 .................................................................459 _POSIX2_PBS_CHECKPOINT ............................442 52 ...............................................................460 _POSIX2_PBS_LOCATE........................................442 53 ..........................................................116 _POSIX2_PBS_MESSAGE.....................................442 54 ................................................................462 _POSIX2_PBS_TRACK..........................................442 55 ..............................................................466 _POSIX2_RE_DUP_MAX.....................283, 286, 290 56 ...........................................................468 _POSIX2_SW_DEV ................................................442 57 ±0................................................................................118 _POSIX2_UPE .................................................437, 443 58 _CS_PATH ...............................................................445 _POSIX2_VERSION...............................................437 59 _CS_XBS5_ILP32_OFF32_CFLAGS....................447 _POSIX_ADVISORY_INFO.....................21, 32, 438 60 _CS_XBS5_ILP32_OFF32_LDFLAGS.................447 _POSIX_AIO_LISTIO_MAX........................282, 287 61 _CS_XBS5_ILP32_OFF32_LIBS............................447 _POSIX_AIO_MAX........................................282, 287 62 _CS_XBS5_ILP32_OFF32_LINTFLAGS.............447 _POSIX_ARG_MAX ......................................282, 287 63 _CS_XBS5_ILP32_OFFBIG_CFLAGS.................447 _POSIX_ASYNCHRONOUS_IO......21, 28, 32, 438 64 _CS_XBS5_ILP32_OFFBIG_LDFLAGS ..............447 _POSIX_ASYNC_IO ..............................................445 65 _CS_XBS5_ILP32_OFFBIG_LIBS.........................447 _POSIX_BARRIERS.............................21, 30, 32, 438 66 _CS_XBS5_ILP32_OFFBIG_LINTFLAGS..........447 _POSIX_BASE ...................................................20, 444 67 _CS_XBS5_LP64_OFF64_CFLAGS .....................447 _POSIX_CHILD_MAX ..........................................287 68 _CS_XBS5_LP64_OFF64_LDFLAGS ..................448 _POSIX_CHOWN_RESTRICTED........21, 438, 457 69 _CS_XBS5_LP64_OFF64_LIBS.............................448 _POSIX_CLOCKRES_MIN...................................286 70 _CS_XBS5_LP64_OFF64_LINTFLAGS ..............448 _POSIX_CLOCK_SELECTION...............21, 32, 438 71 _CS_XBS5_LPBIG_OFFBIG_CFLAGS ...............448 _POSIX_CPUTIME ....................................21, 32, 438 72 _CS_XBS5_LPBIG_OFFBIG_LDFLAGS.............448 _POSIX_C_LANG_SUPPORT.................20, 25, 444 73 _CS_XBS5_LPBIG_OFFBIG_LIBS .......................448 _POSIX_C_LANG_SUPPORT_R ......21, 24-25, 444 74 _CS_XBS5_LPBIG_OFFBIG_LINTFLAGS ........448 _POSIX_DELAYTIMER_MAX ....................282, 287 75 _IOFBF ......................................................................358 _POSIX_DEVICE_IO.................................20, 25, 444 76 _IOLBF......................................................................358 _POSIX_DEVICE_SPECIFIC ...................20, 25, 444 77 _IONBF.....................................................................358 _POSIX_DEVICE_SPECIFIC_R.....................25, 444 78 _MIN .........................................................................281 _POSIX_FD_MGMT ..................................20, 25, 444 79 _PC constants _POSIX_FIFO..............................................20, 25, 444 80 defined in ........................................451 _POSIX_FILE_ATTRIBUTES ...................20, 25, 444 81 _POSIX......................................................................281 _POSIX_FILE_LOCKING...................21, 24-25, 444 82 _POSIX maximum values _POSIX_FILE_SYSTEM ............................20, 25, 444 83 in ........................................................286 _POSIX_FSYNC .............................21, 24, 28, 32, 438 84 _POSIX minimum values _POSIX_IPV6.......................................................21, 32 85 in ........................................................286 _POSIX_JOB_CONTROL...20-21, 26, 439, 444, 457 86 _POSIX2_BC_BASE_MAX ...........................285, 289 _POSIX_LINK_MAX.....................................284, 287 87 _POSIX2_BC_DIM_MAX .............................285, 290 _POSIX_LOGIN_NAME_MAX ..................282, 287 88 _POSIX2_BC_SCALE_MAX ........................285, 290 _POSIX_MAPPED_FILES ............21, 24, 28, 32, 439 89 _POSIX2_BC_STRING_MAX......................286, 290 _POSIX_MAPPED_FILES,......................................28 90 _POSIX2_CHARCLASS_NAME_MAX.....286, 290 _POSIX_MAX_CANON...............................284, 287 91 _POSIX2_CHAR_TERM...............................437, 442 _POSIX_MAX_INPUT ..................................284, 287 92 _POSIX2_COLL_WEIGHTS_MAX ............286, 290 _POSIX_MEMLOCK...........................21, 28, 33, 439 93 _POSIX2_C_BIND..........................................437, 442 _POSIX_MEMLOCK_RANGE..........21, 28, 33, 439 94 _POSIX2_C_DEV....................................................442 _POSIX_MEMORY_PROTECTION...............21, 24 95 _POSIX2_EXPR_NEST_MAX......................286, 290 ....................................................................28, 33, 439 96 _POSIX2_FORT_DEV............................................442 _POSIX_MESSAGE_PASSING .........21, 28, 33, 439 97 _POSIX2_FORT_RUN...........................................442 _POSIX_MONOTONIC_CLOCK...........22, 33, 439 98 _POSIX2_LINE_MAX ...........................286, 290, 292 _POSIX_MQ_OPEN_MAX ..........................282, 287 472 Technical Standard (2000) (Draft July 31, 2000) Index 99 _POSIX_MQ_PRIO_MAX ............................282, 287 ........................................................22, 29-30, 34, 441 100 _POSIX_MULTIPLE_PROCESS..............20, 26, 444 _POSIX_THREAD_PRIO_INHERIT..............22, 29 101 _POSIX_NAME_MAX ..................................285, 287 ..........................................................................34, 440 102 _POSIX_NETWORKING .........................20, 26, 444 _POSIX_THREAD_PRIO_PROTECT ............22, 29 103 _POSIX_NGROUPS_MAX...................................288 ..........................................................................34, 441 104 _POSIX_NO_TRUNC .............................21, 439, 457 _POSIX_THREAD_PROCESS_SHARED............22 105 _POSIX_OPEN_MAX............................................288 ....................................................................24, 34, 441 106 _POSIX_PATH_MAX ....................................285, 288 _POSIX_THREAD_SAFE_FUNCTIONS.............22 107 _POSIX_PIPE ..............................................20, 26, 444 .............................................................24, 30, 34, 441 108 _POSIX_PIPE_BUF ........................................285, 288 _POSIX_THREAD_SPORADIC_SERVER ..........22 109 _POSIX_PRIORITIZED_IO................22, 28, 33, 439 ....................................................................30, 34, 441 110 _POSIX_PRIORITY_SCHEDULING22, 28, 33, 439 _POSIX_THREAD_THREADS_MAX........283, 289 111 _POSIX_PRIO_IO...................................................445 _POSIX_TIMEOUTS..................................22, 34, 441 112 _POSIX_RAW_SOCKETS.......................................22 _POSIX_TIMERS............................22, 28, 30, 34, 441 113 _POSIX_READER_WRITER_LOCKS ................439 _POSIX_TIMER_MAX ..................................283, 289 114 _POSIX_REALTIME_SIGNALS........22, 28, 33, 439 _POSIX_TTY_NAME_MAX ........................284, 289 115 _POSIX_REGEXP ...................................................439 _POSIX_TYPED_MEMORY_OBJECTS.22, 35, 441 116 _POSIX_RE_DUP_MAX .......................................288 _POSIX_TZNAME_MAX.............................284, 289 117 _POSIX_RTSIG_MAX ...................................283, 288 _POSIX_USER_GROUPS .........................20, 26, 444 118 _POSIX_SAVED_IDS...............................21, 440, 457 _POSIX_USER_GROUPS_R ..............21, 24, 26, 444 119 _POSIX_SEMAPHORES.....................22, 28, 33, 440 _POSIX_VDISABLE.................................21, 441, 457 120 _POSIX_SEM_NSEMS_MAX ......................283, 288 _POSIX_VERSION.................................................437 121 _POSIX_SEM_VALUE_MAX.......................283, 288 _SC constants 122 _POSIX_SHARED_MEMORY_OBJECTS............22 defined in ........................................448 123 ....................................................................28, 33, 440 _SC_COLL_WIGHTS_MAX ................................456 124 _POSIX_SHELL ................................................33, 440 _SC_EXPR_NEST_MAX .......................................456 125 _POSIX_SIGNALS .....................................20, 26, 444 _SC_LINE_MAX.....................................................456 126 _POSIX_SIGQUEUE_MAX..........................283, 288 _SC_RE_DUP_MAX ..............................................456 127 _POSIX_SINGLE_PROCESS ...................20, 26, 444 _SC_STREAM_MAX..............................................456 128 _POSIX_SPAWN........................................22, 33, 440 _SC_TZNAME_MAX ............................................456 129 _POSIX_SPIN_LOCKS .......................22, 30, 33, 440 _XBS5_ILP32_OFF32..............................................443 130 _POSIX_SPORADIC_SERVER................22, 33, 440 _XBS5_ILP32_OFFBIG...........................................443 131 _POSIX_SSIZE_MAX ....................................288, 291 _XBS5_LP64_OFF64...............................................443 132 _POSIX_SS_REPL_MAX...............................283, 288 _XBS5_LPBIG_OFFBIG .........................................443 133 _POSIX_STREAM_MAX ..............................283, 288 _XOPEN_CRYPT .................................22, 24, 27, 443 134 _POSIX_SYMLINK_MAX ............................285, 289 _XOPEN_ENH_I18N.............................................443 135 _POSIX_SYMLOOP_MAX...........................283, 289 _XOPEN_IOV_MAX .....................................282, 290 136 _POSIX_SYNCHRONIZED_IO........22, 28, 34, 440 _XOPEN_LEGACY........................22, 24, 31-32, 443 137 _POSIX_SYNC_IO .................................................445 _XOPEN_REALTIME.....................23-24, 27-28, 443 138 _POSIX_SYSTEM_DATABASE ...............20, 26, 444 _XOPEN_REALTIME_THREADS ....23-24, 29, 443 139 _POSIX_SYSTEM_DATABASE_R....21, 24, 26, 444 _XOPEN_SHM........................................................443 140 _POSIX_THREADS.......................22, 24, 30, 34, 441 _XOPEN_STREAMS........................................31, 444 141 _POSIX_THREAD_ATTR_STACKADDR.....22, 24 _XOPEN_UNIX ................................................23, 437 142 ..........................................................................34, 440 _XOPEN_VERSION...............................................437 143 _POSIX_THREAD_ATTR_STACKSIZE ........22, 24 _XOPEN_XCU_VERSION....................................437 144 ..........................................................................34, 440 _XOPEN_XPG2.......................................................437 145 _POSIX_THREAD_CPUTIME ..........22, 30, 34, 440 _XOPEN_XPG3.......................................................437 146 _POSIX_THREAD_DESTRUCTOR_........................ _XOPEN_XPG4.......................................................438 147 ITERATIONS...................................................283, 289 ABDAY_....................................................................278 148 _POSIX_THREAD_KEYS_MAX.................283, 289 ABMON_..................................................................278 149 _POSIX_THREAD_PRIORITY_SCHEDULING .... abortive release .........................................................41 Base Definitions, Issue 6 473 Index 150 absolute path name..........................................41, 123 asynchronously-generated signal .........................45 151 access mode ...............................................................41 ATEXIT_MAX .........................................................282 152 additional file access control mechanism............41 attribute selection...................................................420 153 address space.............................................................41 authentication............................................................46 154 ADV.............................................................................10 authorization .............................................................46 155 advisory information...............................................41 background job .........................................................46 156 affirmative response ................................................42 background process .................................................46 157 AF_INET...................................................................391 background process group.....................................46 158 AF_INET6 ................................................................391 backquote ...................................................................47 159 AF_UNIX..................................................................391 backslash ....................................................................47 160 AF_UNSPEC............................................................391 backspace character .................................................47 161 AIO ..............................................................................10 bandinfo....................................................................369 162 AIO_ALLDONE .....................................................232 BAR..............................................................................10 163 AIO_CANCELED...................................................232 barrier..........................................................................47 164 AIO_LISTIO_MAX.................................................281 base character............................................................47 165 AIO_MAX ................................................................282 basename....................................................................47 166 AIO_NOTCANCELED .........................................232 basic regular expression..................................48, 198 167 AIO_PRIO_DELTA_MAX.....................................282 batch access list .........................................................48 168 AI_CANONNAME................................................311 batch administrator..................................................48 169 AI_NUMERICHOST..............................................311 batch client .................................................................48 170 AI_PASSIVE.............................................................311 batch destination ......................................................48 171 alert..............................................................................42 batch destination identifier.....................................48 172 alert character............................................................42 batch directive...........................................................49 173 alias name...................................................................42 batch job......................................................................49 174 alignment....................................................................42 batch job attribute.....................................................49 175 alternate file access control mechanism ..............43 batch job identifier....................................................49 176 alternate signal stack................................................43 batch job name ..........................................................49 177 ALT_DIGITS............................................................278 batch job owner.........................................................50 178 AM_STR ...................................................................278 batch job priority ......................................................50 179 anchoring..................................................................202 batch job state............................................................50 180 ancillary data .............................................................43 batch name service...................................................50 181 angle brackets............................................................43 batch name space......................................................50 182 ANYMARK..............................................................372 batch node..................................................................50 183 API ...............................................................................44 batch operator ...........................................................51 184 application .................................................................43 batch queue................................................................51 185 application address ..................................................43 batch queue attribute...............................................51 186 application conformance ........................................38 batch queue position................................................51 187 application program interface ...............................44 batch queue priority.................................................51 188 appropriate privileges .............................................44 batch rerunability .....................................................52 189 AREGTYPE..............................................................415 batch restart ...............................................................52 190 argument ....................................................................44 batch server................................................................52 191 ARG_MAX...............................................................282 batch server name.....................................................52 192 arm (a timer)..............................................................44 batch service ..............................................................52 193 assignment .................................................................44 batch service request................................................52 194 asterisk........................................................................45 batch submission ......................................................53 195 async-cancel-safe function......................................45 batch system ..............................................................53 196 async-signal-safe function ......................................45 batch target user .......................................................53 197 asynchronous events ...............................................45 batch user ...................................................................53 198 asynchronous I/O completion ..............................46 baud rate selection .................................................419 199 asynchronous I/O operation .................................46 BC_BASE_MAX ......................................................285 200 asynchronous input and output............................45 BC_DIM_MAX........................................................285 474 Technical Standard (2000) (Draft July 31, 2000) Index 201 BC_SCALE_MAX ...................................................285 CHILD_MAX...........................................................282 202 BC_STRING_MAX.................................................286 CHRTYPE ................................................................415 203 BE .................................................................................10 circumflex...................................................................57 204 bind..............................................................................53 CLD_CONTINUED ...............................................342 205 blank character..........................................................53 CLD_DUMPED.......................................................342 206 blank line ....................................................................53 CLD_EXITED ..........................................................342 207 blkcnt_t .....................................................................405 CLD_KILLED ..........................................................342 208 blksize_t....................................................................405 CLD_STOPPED.......................................................342 209 BLKTYPE..................................................................415 CLD_TRAPPED......................................................342 210 block special file........................................................54 CLOCAL...................................................................420 211 block-mode terminal................................................54 clock.............................................................................57 212 blocked process (or thread) ....................................54 clock jump..................................................................57 213 blocking ......................................................................54 clock tick.....................................................................58 214 BOOT_TIME............................................................460 clockid_t ...................................................................405 215 braces...........................................................................54 CLOCKS_PER_SEC ...............................405, 427-428 216 brackets.......................................................................54 CLOCK_MONOTONIC .......................................428 217 BRE (ERE) matching a single character .............196 CLOCK_PROCESS_CPUTIME_ID.....................427 218 BRE (ERE) matching multiple characters..........196 CLOCK_REALTIME......................................286, 427 219 break value.................................................................55 clock_t .......................................................................405 220 BRKINT ....................................................................418 CLOCK_THREAD_CPUTIME_ID......................427 221 broadcast ....................................................................55 CMSG_DATA ..........................................................390 222 BSD ............................................................................244 CMSG_FIRSTHDR.................................................390 223 BSDLY .......................................................................419 CMSG_NXTHDR ...................................................390 224 BSn.............................................................................419 coded character set...................................................58 225 BUFSIZ......................................................................358 codeset ........................................................................58 226 built-in.........................................................................55 CODESET.................................................................278 227 built-in utility ............................................................55 collating element.......................................................58 228 BUS_ADRALN........................................................342 collating element order............................................58 229 BUS_ADRERR.........................................................342 collation ......................................................................59 230 BUS_OBJERR...........................................................342 collation sequence ....................................................59 231 byte ..............................................................................55 COLL_WEIGHTS_MAX .......................................286 232 byte input/output functions ..................................56 column position ........................................................59 233 can..................................................................................8 COLUMNS...............................................................192 234 canonical mode input processing .......................215 command....................................................................59 235 carriage-return character.........................................56 command language interpreter.............................60 236 CD................................................................................10 composite graphic symbol......................................60 237 character .....................................................................56 condition variable.....................................................60 238 character array...........................................................56 conformance........................................................19, 38 239 character class ...........................................................56 POSIX......................................................................19 240 character encoding .................................................136 POSIX system interfaces.....................................20 241 state-dependent ..................................................140 XSI............................................................................19 242 character set...............................................................57 XSI system interfaces...........................................23 243 character special file.................................................57 conformance document...........................................19 244 character string..........................................................57 conforming application...........................................19 245 CHARCLASS_NAME_MAX.......................286, 292 conforming implementation options ...................25 246 charmap connection..................................................................60 247 description ...........................................................137 connection mode.......................................................60 248 CHAR_BIT ...............................................................290 connectionless mode................................................60 249 CHAR_MAX............................................................291 control character .......................................................61 250 CHAR_MIN.............................................................291 control modes..........................................................420 251 child process ..............................................................57 control operator ........................................................61 Base Definitions, Issue 6 475 Index 252 controlling process ...................................................61 utimbuf.................................................................459 253 controlling terminal .........................................61, 214 data type 254 CONTTYPE .............................................................415 ACTION...............................................................333 255 conversion descriptor ..............................................61 cc_t.........................................................................417 256 core file........................................................................61 DIR.........................................................................244 257 CPT ..............................................................................11 div_t ......................................................................362 258 CPU ...........................................................................404 ENTRY..................................................................333 259 CPU time ....................................................................62 FILE .......................................................................359 260 clock ........................................................................62 fpos_t ....................................................................359 261 timer ........................................................................62 glob_t ....................................................................268 262 CRDLY ......................................................................418 ldiv_t .....................................................................362 263 CREAD .....................................................................420 mbstate_t..............................................................462 264 CRn............................................................................418 msglen_t ...............................................................379 265 CRNCYSTR .............................................................278 msgqnum_t..........................................................379 266 CS.................................................................................11 nl_catd ..................................................................319 267 CSIZE ........................................................................420 nl_item..................................................................319 268 CSn.............................................................................420 ptrdiff_t ................................................................351 269 CSTOPB....................................................................420 regex_t ..................................................................329 270 current working directory ..............................62, 117 regmatch_t ...........................................................329 271 cursor position ..........................................................62 regoff_t .................................................................329 272 CX ................................................................................11 shmatt_t................................................................387 273 C_ constants in .......................................240 sigset_t..................................................................338 274 C_IRGRP ..................................................................240 sig_atomic_t ........................................................338 275 C_IROTH .................................................................240 size_t .....................................................................351 276 C_IRUSR...................................................................240 speed_t..................................................................417 277 C_ISBLK ...................................................................240 tcflag_t ..................................................................417 278 C_ISCHR ..................................................................240 VISIT .....................................................................333 279 C_ISCTG...................................................................240 wchar_t.................................................................351 280 C_ISDIR....................................................................240 wctrans_t..............................................................466 281 C_ISFIFO ..................................................................240 wctype_t...............................................................462 282 C_ISGID....................................................................240 wint_t....................................................................462 283 C_ISLNK ..................................................................240 data types 284 C_ISREG...................................................................240 defined in ..................................405 285 C_ISSOCK................................................................240 DATEMSK................................................................192 286 C_ISUID....................................................................240 DAY_ .........................................................................278 287 C_ISVTX...................................................................240 DBL_ constants 288 C_IWGRP.................................................................240 defined in ............................................261 289 C_IWOTH................................................................240 DBL_DIG..........................................................261, 290 290 C_IWUSR .................................................................240 DBL_EPSILON........................................................262 291 C_IXGRP ..................................................................240 DBL_MANT_DIG...................................................261 292 C_IXOTH .................................................................240 DBL_MAX........................................................262, 290 293 C_IXUSR...................................................................240 DBL_MAX_10_EXP................................................262 294 data segment..............................................................63 DBL_MAX_EXP......................................................261 295 data structure DBL_MIN.................................................................262 296 dirent.....................................................................244 DBL_MIN_10_EXP.................................................261 297 entry ......................................................................333 DBL_MIN_EXP .......................................................261 298 group.....................................................................270 DBM...........................................................................308 299 lconv......................................................................296 DBM_INSERT .........................................................308 300 msqid_ds..............................................................379 DBM_REPLACE .....................................................308 301 stat .........................................................................394 DEAD_PROCESS ...................................................460 302 tms.........................................................................404 deferred batch service..............................................63 476 Technical Standard (2000) (Draft July 31, 2000) Index 303 DELAYTIMER_MAX .............................................282 EDESTADDRREQ ..................................................247 304 device ..........................................................................63 EDOM .......................................................................247 305 output ...................................................................211 EDQUOT ..................................................................247 306 device ID.....................................................................63 EEXIST ......................................................................247 307 dev_t..........................................................................405 EFAULT ....................................................................247 308 DIR.............................................................................244 EFBIG ........................................................................247 309 directory .....................................................................63 effective group ID.....................................................65 310 directory entry (or link)...........................................63 effective user ID........................................................65 311 directory stream........................................................63 EHOSTUNREACH ................................................247 312 dirent structure .......................................................244 EIDRM ......................................................................247 313 DIRTYPE ..................................................................415 eight-bit transparency..............................................65 314 disarm (a timer).........................................................64 EILSEQ......................................................................247 315 display.........................................................................64 EINPROGRESS .......................................................248 316 documentation ..........................................................19 EINTR .......................................................................248 317 dollar sign...................................................................64 EINVAL ....................................................................248 318 dot................................................................................64 EIO.............................................................................248 319 dot-dot ........................................................................64 EISCONN.................................................................248 320 double-quote..............................................................64 EISDIR.......................................................................248 321 downshifting .............................................................65 ELOOP......................................................................248 322 driver...........................................................................65 EMFILE.....................................................................248 323 D_FMT ......................................................................278 EMLINK ...................................................................248 324 D_T_FMT .................................................................278 EMPTY......................................................................460 325 E2BIG ........................................................................247 empty directory.........................................................65 326 EACCES....................................................................247 empty line...................................................................66 327 EADDRINUSE ........................................................247 empty string (or null string)...................................66 328 EADDRNOTAVAIL................................................247 empty wide-character string..................................66 329 EAFNOSUPPORT ..................................................247 EMSGSIZE ...............................................................248 330 EAGAIN ...................................................................247 EMULTIHOP...........................................................248 331 EAI_AGAIN ............................................................312 ENAMETOOLONG...............................................248 332 EAI_BADFLAGS.....................................................312 encoding 333 EAI_FAIL..................................................................312 character...............................................................136 334 EAI_FAMILY ...........................................................312 encoding rule.............................................................66 335 EAI_MEMORY........................................................312 encryption ..................................................................27 336 EAI_NONAME.......................................................312 ENETDOWN...........................................................248 337 EAI_SERVICE..........................................................312 ENETUNREACH ...................................................248 338 EAI_SOCKTYPE.....................................................312 ENFILE .....................................................................248 339 EAI_SYSTEM...........................................................312 ENOBUFS.................................................................248 340 EALREADY .............................................................247 ENODATA ...............................................................248 341 EBADF ......................................................................247 ENODEV ..................................................................248 342 EBADMSG ...............................................................247 ENOENT ..................................................................248 343 EBUSY.......................................................................247 ENOEXEC ................................................................248 344 ECANCELED ..........................................................247 ENOLCK ..................................................................248 345 ECHILD....................................................................247 ENOLINK ................................................................248 346 ECHO........................................................................420 ENOMEM.................................................................248 347 ECHOE .....................................................................420 ENOMSG..................................................................248 348 ECHOK.....................................................................420 ENOPROTOOPT....................................................248 349 ECHONL..................................................................420 ENOSPC ...................................................................248 350 ECONNABORTED ................................................247 ENOSR......................................................................248 351 ECONNREFUSED..................................................247 ENOSTR ...................................................................248 352 ECONNRESET........................................................247 ENOSYS....................................................................248 353 EDEADLK................................................................247 ENOTCONN...........................................................248 Base Definitions, Issue 6 477 Index 354 ENOTDIR.................................................................248 FD.................................................................................11 355 ENOTEMPTY..........................................................248 FD_CLOEXEC.........................................................251 356 ENOTSOCK.............................................................248 FD_CLR ....................................................................401 357 ENOTSUP ................................................................248 FD_ISSET..................................................................401 358 ENOTTY...................................................................249 FD_SET .....................................................................401 359 entire regular expression ................................66, 196 fd_set.........................................................................401 360 environment variables FD_SETSIZE ............................................................401 361 internationalization............................................189 FD_ZERO .................................................................401 362 ENXIO.......................................................................249 feature test macro.....................................................68 363 EOF............................................................................358 FFDLY .......................................................................419 364 EOPNOTSUPP........................................................249 FFn .............................................................................419 365 EOVERFLOW..........................................................249 field..............................................................................68 366 EPERM......................................................................249 FIFO.............................................................................69 367 EPIPE.........................................................................249 FIFO special file ........................................................69 368 epoch ...........................................................................66 FIFOTYPE ................................................................415 369 EPROTO ...................................................................249 file ................................................................................69 370 EPROTONOSUPPORT .........................................249 FILE ...................................................................358, 462 371 EPROTOTYPE.........................................................249 file access permissions...........................................121 372 equivalence class ......................................................66 file characteristics 373 era.................................................................................67 data structure ......................................................396 374 ERA............................................................................278 header ...................................................................396 375 ERANGE ..................................................................249 file description...........................................................69 376 ERA_D_FMT ...........................................................278 file descriptor.............................................................69 377 ERA_D_T_FMT.......................................................278 file group class ..........................................................69 378 ERA_T_FMT ............................................................278 file mode.....................................................................70 379 EROFS.......................................................................249 file mode bits .............................................................70 380 ESPIPE.......................................................................249 file name .....................................................................70 381 ESRCH ......................................................................249 file name portability.................................................70 382 ESTALE.....................................................................249 file offset .....................................................................70 383 ETIME .......................................................................249 file other class............................................................71 384 ETIMEDOUT...........................................................249 file owner class..........................................................71 385 ETXTBSY ..................................................................249 file permission bits ...................................................71 386 event management...................................................67 file serial number......................................................71 387 EWOULDBLOCK...................................................249 file system ..................................................................71 388 EXDEV ......................................................................249 file times update .....................................................122 389 executable file............................................................67 file type .......................................................................71 390 execute ........................................................................67 FILENAME_MAX ..................................................358 391 execution time.....................................................62, 67 FILESIZEBITS..........................................................284 392 measurement.......................................................123 filter .............................................................................72 393 monitoring .............................................................67 FIPS..............................................................................21 394 EXIT_FAILURE.......................................................362 first open (of a file) ...................................................72 395 EXIT_SUCCESS ......................................................362 flow control................................................................72 396 expand.........................................................................68 FLT_ constants 397 EXPR_NEST_MAX.................................................286 defined in ............................................261 398 extended regular expression..........................68, 203 FLT_DIG...........................................................261, 290 399 extended security controls......................................68 FLT_EPSILON.........................................................262 400 extension FLT_MANT_DIG....................................................261 401 CX ............................................................................11 FLT_MAX.........................................................262, 290 402 OH ...........................................................................12 FLT_MAX_10_EXP.................................................261 403 XSI............................................................................16 FLT_MAX_EXP .......................................................261 404 F-LOCK.....................................................................451 FLT_MIN ..................................................................262 478 Technical Standard (2000) (Draft July 31, 2000) Index 405 FLT_MIN_10_EXP..................................................261 F_GETLK..................................................................251 406 FLT_MIN_EXP ........................................................261 F_GETOWN ............................................................251 407 FLT_RADIX .....................................................259, 261 F_OK .........................................................................445 408 FLT_ROUNDS.........................................................259 F_RDLCK .................................................................251 409 FLUSHR....................................................................370 F_SETFD...................................................................251 410 FLUSHRW ...............................................................370 F_SETFL....................................................................251 411 FLUSHW ..................................................................370 F_SETLK...................................................................251 412 FMNAMESZ............................................................370 F_SETLKW...............................................................251 413 FNM_ constants F_SETOWN .............................................................251 414 in ....................................................265 F_TEST......................................................................451 415 FNM_NOESCAPE..................................................265 F_TLOCK .................................................................451 416 FNM_NOMATCH..................................................265 F_ULOCK.................................................................451 417 FNM_NOSYS ..........................................................265 F_UNLCK.................................................................251 418 FNM_PATHNAME................................................265 F_WRLCK ................................................................251 419 FNM_PERIOD.........................................................265 GETALL....................................................................385 420 FOPEN_MAX..................................................283, 358 GETNCNT ...............................................................385 421 foreground job...........................................................72 GETPID.....................................................................385 422 foreground process ..................................................72 GETVAL ...................................................................385 423 foreground process group ......................................72 GETZCNT................................................................385 424 foreground process group ID.................................72 gid_t...........................................................................405 425 form-feed character..................................................73 GLOB_ constants 426 format of entries......................................................231 defined in ............................................268 427 FPE_FLTDIV............................................................342 GLOB_ABORTED ..................................................268 428 FPE_FLTINV............................................................342 GLOB_APPEND .....................................................268 429 FPE_FLTOVF...........................................................342 GLOB_DOOFFS......................................................268 430 FPE_FLTRES ............................................................342 GLOB_ERR ..............................................................268 431 FPE_FLTSUB............................................................342 GLOB_MARK..........................................................268 432 FPE_FLTUND..........................................................342 GLOB_NOCHECK.................................................268 433 FPE_INTDIV............................................................342 GLOB_NOESCAPE................................................268 434 FPE_INTOVF...........................................................342 GLOB_NOMATCH................................................268 435 FR .................................................................................11 GLOB_NOSORT.....................................................268 436 fsblkcnt_t..................................................................405 GLOB_NOSPACE ..................................................268 437 FSC...............................................................................11 GLOB_NOSYS.........................................................268 438 fsfilcnt_t....................................................................405 grammar 439 FTW...........................................................................266 locale .....................................................................176 440 FTW_ constants regular expression..............................................206 441 in .............................................................266 graphic character ......................................................73 442 FTW_CHDIR...........................................................266 group database..........................................................73 443 FTW_D......................................................................266 group ID .....................................................................73 444 FTW_DEPTH...........................................................266 group name................................................................73 445 FTW_DNR ...............................................................266 hard limit....................................................................74 446 FTW_DP ...................................................................266 hard link......................................................................74 447 FTW_F.......................................................................266 headers......................................................................231 448 FTW_MOUNT ........................................................266 HOME.......................................................................192 449 FTW_NS ...................................................................266 home directory..........................................................74 450 FTW_PHYS..............................................................266 host byte order ..........................................................74 451 FTW_SL ....................................................................266 HUGE_VAL .............................................................299 452 FTW_SLN.................................................................266 HUPCL .....................................................................420 453 F_DUPFD .................................................................251 ICANON ..................................................................420 454 F_GETFD..................................................................251 ICRNL.......................................................................418 455 F_GETFL...................................................................251 idtype_t.....................................................................411 Base Definitions, Issue 6 479 Index 456 id_t.............................................................................405 IPC_EXCL ................................................................374 457 IEXTEN.....................................................................420 IPC_NOWAIT .........................................................374 458 IGNBRK....................................................................418 IPC_PRIVATE..........................................................374 459 IGNCR ......................................................................418 IPC_RMID................................................................374 460 IGNPAR....................................................................418 IPC_SET....................................................................374 461 ILL_BADSTK...........................................................342 IPC_STAT .................................................................374 462 ILL_COPROC..........................................................342 IPPROTO_ICMP.....................................................315 463 ILL_ILLADR............................................................342 IPPROTO_IP............................................................315 464 ILL_ILLOPC ............................................................342 IPPROTO_TCP........................................................315 465 ILL_ILLOPN............................................................342 IPPROTO_UDP.......................................................315 466 ILL_ILLTRP..............................................................342 IPV6_JOIN_GROUP ..............................................315 467 ILL_PRVOPC...........................................................342 IPV6_LEAVE_GROUP...........................................315 468 ILL_PRVREG...........................................................342 IPV6_MULTICAST_HOPS ...................................316 469 implementation-defined ...........................................8 IPV6_MULTICAST_IF...........................................316 470 IN6_IS_ADDR_LINKLOCAL..............................316 IPV6_MULTICAST_LOOP...................................316 471 IN6_IS_ADDR_LOOPBACK................................316 IPV6_UNICAST_HOPS ........................................316 472 IN6_IS_ADDR_MC_GLOBAL.............................316 ISIG............................................................................420 473 IN6_IS_ADDR_MC_LINKLOCAL.....................316 ISTRIP .......................................................................418 474 IN6_IS_ADDR_MC_NODELOCAL...................316 itimerval ...................................................................401 475 IN6_IS_ADDR_MC_ORGLOCAL......................316 ITIMER_PROF.........................................................401 476 IN6_IS_ADDR_MC_SITELOCAL.......................316 ITIMER_REAL ........................................................401 477 IN6_IS_ADDR_MULTICAST...............................316 ITIMER_VIRTUAL.................................................401 478 IN6_IS_ADDR_SITELOCAL................................316 IXANY ......................................................................418 479 IN6_IS_ADDR_UNSPECIFIED ...........................316 IXOFF........................................................................418 480 IN6_IS_ADDR_V4COMPAT................................316 IXON .........................................................................418 481 IN6_IS_ADDR_V4MAPPED................................316 I_ATMARK ..............................................................372 482 INADDR_ANY .......................................................315 I_CANPUT...............................................................372 483 INADDR_BROADCAST.......................................315 I_CKBAND ..............................................................372 484 incomplete line..........................................................74 I_FDINSERT ............................................................371 485 INET6_ADDRSTRLEN .........................................315 I_FIND ......................................................................371 486 INET_ADDRSTRLEN............................................315 I_FLUSH...................................................................370 487 Inf.................................................................................74 I_FLUSHBAND.......................................................370 488 INIT_PROCESS.......................................................460 I_GETBAND............................................................372 489 INLCR.......................................................................418 I_GETCLTIME.........................................................372 490 ino_t...........................................................................405 I_GETSIG..................................................................371 491 INPCK.......................................................................418 I_GRDOPT ...............................................................371 492 interactive shell.........................................................75 I_GWROPT ..............................................................371 493 internationalization..................................................75 I_LINK ......................................................................372 494 interprocess communication..................................75 I_LIST........................................................................372 495 INT_MAX.................................................................291 I_LOOK.....................................................................370 496 INT_MIN..................................................................291 I_NREAD .................................................................371 497 invalid .......................................................................196 I_PEEK ......................................................................371 498 invariant values ......................................................292 I_PLINK....................................................................372 499 invoke..........................................................................75 I_POP ........................................................................370 500 iovec ..........................................................................408 I_PUNLINK.............................................................372 501 IOV_MAX ................................................................282 I_PUSH .....................................................................370 502 IP6 ................................................................................11 I_RECVFD................................................................372 503 IPC .............................................................................374 I_SENDFD................................................................371 504 IPC_ constants I_SETCLTIME..........................................................372 505 defined in ......................................374 I_SETSIG...................................................................370 506 IPC_CREAT .............................................................374 I_SRDOPT ................................................................371 480 Technical Standard (2000) (Draft July 31, 2000) Index 507 I_STR.........................................................................371 local customs .............................................................77 508 I_SWROPT ...............................................................371 local IPC......................................................................77 509 I_UNLINK................................................................372 local modes ..............................................................420 510 job.................................................................................75 locale ...................................................................77, 143 511 job control...................................................................76 grammar...............................................................176 512 job control job ID ......................................................76 POSIX....................................................................144 513 key_t..........................................................................405 locale definition ......................................................145 514 LANG........................................................................189 localization.................................................................77 515 last close (of a file) ....................................................76 login.............................................................................77 516 LASTMARK.............................................................372 login name..................................................................78 517 LC_ALL............................................................189, 296 LOGIN_NAME_MAX...........................................282 518 LC_COLLATE.........................................189, 286, 296 LOGIN_PROCESS..................................................460 519 description ...........................................................155 LOGNAME..............................................................192 520 LC_CTYPE ......................................189, 278, 296, 466 LOG_ALERT ...........................................................414 521 description ...........................................................147 LOG_AUTH.............................................................413 522 LC_MESSAGES..............................189, 278, 296, 319 LOG_CONS.............................................................413 523 description ...........................................................174 LOG_CRIT ...............................................................414 524 LC_MONETARY....................................189, 278, 296 LOG_CRON ............................................................413 525 description ...........................................................163 LOG_DAEMON .....................................................413 526 LC_NUMERIC........................................189, 278, 296 LOG_DEBUG ..........................................................414 527 description ...........................................................166 LOG_EMERG ..........................................................414 528 LC_TIME..................................................190, 278, 296 LOG_ERR.................................................................414 529 description ...........................................................168 LOG_INFO...............................................................414 530 LDBL_ constants LOG_KERN .............................................................413 531 defined in ............................................261 LOG_LOCAL...........................................................413 532 LDBL_DIG................................................................261 LOG_LPR .................................................................413 533 LDBL_EPSILON .....................................................262 LOG_MAIL..............................................................413 534 LDBL_MANT_DIG ................................................261 LOG_MASK.............................................................413 535 LDBL_MAX .............................................................262 LOG_NDELAY........................................................413 536 LDBL_MAX_10_EXP .............................................262 LOG_NEWS.............................................................413 537 LDBL_MAX_EXP....................................................261 LOG_NOTICE.........................................................414 538 LDBL_MIN...............................................................262 LOG_NOWAIT .......................................................413 539 LDBL_MIN_10_EXP ..............................................261 LOG_ODELAY........................................................413 540 LDBL_MIN_EXP.....................................................261 LOG_PID..................................................................413 541 legacy ......................................................................8, 31 LOG_USER ..............................................................413 542 limit LOG_UUCP .............................................................413 543 numerical .............................................................290 LOG_WARNING ...................................................414 544 line ...............................................................................76 LONG_BIT .......................................................290-291 545 line control ...............................................................421 LONG_MAX............................................................291 546 LINES........................................................................192 LONG_MIN.............................................................292 547 LINE_MAX ..............................................................286 lower multiplexing.................................................103 548 linger............................................................................76 L_ctermid .................................................................358 549 link ...............................................................................77 L_tmpnam................................................................358 550 link count....................................................................77 MAGIC .....................................................................240 551 LINK_MAX..............................................................284 MAN............................................................................11 552 LIO_NOP..................................................................232 map..............................................................................78 553 LIO_NOWAIT.........................................................232 MAP_FIXED ............................................................376 554 LIO_READ ...............................................................232 MAP_PRIVATE .......................................................376 555 LIO_WAIT................................................................232 MAP_SHARED.......................................................376 556 LIO_WRITE .............................................................232 margin codes 557 LNKTYPE.................................................................415 notation...................................................................17 Base Definitions, Issue 6 481 Index 558 marked message .......................................................78 mode............................................................................79 559 matched..............................................................78, 196 mode_t ......................................................................405 560 MAXARGS...............................................................349 MON............................................................................12 561 MAXFLOAT.............................................................299 monotonic clock........................................................80 562 maximum values....................................................286 MON_ .......................................................................278 563 MAX_CANON........................................................284 MORECTL................................................................372 564 MAX_INPUT...........................................................284 MOREDATA ............................................................372 565 may ................................................................................8 mount point ...............................................................80 566 MB_CUR_MAX.......................................................362 MPR.............................................................................12 567 MB_LEN_MAX ...............................................290-291 MQ_OPEN_MAX...................................................282 568 MCL_CURRENT ....................................................376 MQ_PRIO_MAX.....................................................282 569 MCL_FUTURE........................................................376 MSG.............................................................................12 570 mcontext_t ...............................................................435 MSGVERB................................................................192 571 memory mapped files..............................................78 MSG_ANY ...............................................................372 572 memory object...........................................................78 MSG_BAND ............................................................372 573 memory-resident ......................................................79 MSG_CTRUNC.......................................................391 574 message.......................................................................79 MSG_DONTROUTE..............................................391 575 message catalog ........................................................79 MSG_EOR ................................................................391 576 message catalog descriptor ....................................79 MSG_HIPRI .............................................................372 577 message queue ..........................................................79 MSG_NOERROR....................................................379 578 MF................................................................................11 MSG_OOB................................................................391 579 minimum values.....................................................286 MSG_PEEK ..............................................................391 580 MINSIGSTKSZ........................................................340 MSG_TRUNC..........................................................391 581 ML................................................................................12 MSG_WAITALL......................................................391 582 MLR.............................................................................12 MS_ASYNC .............................................................376 583 MM_ macros............................................................263 MS_INVALIDATE ..................................................376 584 MM_APPL................................................................263 MS_SYNC ................................................................376 585 MM_CONSOLE......................................................263 multi-character collating element .........................80 586 MM_ERROR............................................................263 mutex ..........................................................................80 587 MM_FIRM................................................................263 MUXID_ALL ...........................................................372 588 MM_HALT...............................................................263 M_ ..............................................................................298 589 MM_HARD..............................................................263 M_E............................................................................298 590 MM_INFO................................................................263 M_LN ........................................................................298 591 MM_NOCON..........................................................264 M_LOG10E ..............................................................298 592 MM_NOMSG ..........................................................263 M_LOG2E.................................................................298 593 MM_NOSEV............................................................263 M_PI ..........................................................................298 594 MM_NOTOK...........................................................263 M_SQRT1_2.............................................................299 595 MM_NRECOV ........................................................263 M_SQRT2 .................................................................299 596 MM_NULLACT......................................................263 name............................................................................80 597 MM_NULLLBL.......................................................263 named STREAM .......................................................80 598 MM_NULLMC........................................................263 NAME_MAX...................................................244, 285 599 MM_NULLSEV.......................................................263 NaN (Not a Number) ..............................................81 600 MM_NULLTAG ......................................................263 native language.........................................................81 601 MM_NULLTXT.......................................................263 NCCS ........................................................................417 602 MM_OK....................................................................263 NDEBUG..................................................................235 603 MM_OPSYS .............................................................263 negative response.....................................................81 604 MM_PRINT .............................................................263 network.......................................................................81 605 MM_RECOVER ......................................................263 network address .......................................................81 606 MM_SOFT................................................................263 network byte order...................................................81 607 MM_UTIL.................................................................263 newline character......................................................82 608 MM_WARNING.....................................................263 NEW_TIME .............................................................460 482 Technical Standard (2000) (Draft July 31, 2000) Index 609 NGROUPS_MAX ...................................................286 operand.......................................................................84 610 nice value....................................................................82 operator ......................................................................84 611 NI_DGRAM.............................................................312 OPOST ......................................................................418 612 NI_NAMEREQD ....................................................312 option ..........................................................................84 613 NI_NOFQDN..........................................................311 ADV.........................................................................10 614 NI_NUMERICHOST .............................................311 AIO ..........................................................................10 615 NI_NUMERICSERV ..............................................312 BAR..........................................................................10 616 NLDLY......................................................................418 BE.............................................................................10 617 nlink_t .......................................................................405 CD............................................................................10 618 NLn............................................................................418 CPT..........................................................................11 619 NLSPATH.................................................................190 CS.............................................................................11 620 NL_ARGMAX.........................................................292 FD.............................................................................11 621 NL_CAT_LOCALE.................................................319 FR.............................................................................11 622 NL_LANGMAX......................................................292 FSC...........................................................................11 623 NL_MSGMAX.........................................................292 IP6............................................................................11 624 NL_NMAX...............................................................292 MF............................................................................11 625 NL_SETD..................................................................319 ML............................................................................12 626 NL_SETMAX...........................................................292 MLR.........................................................................12 627 NL_TEXTMAX........................................................292 MON .......................................................................12 628 NOEXPR...................................................................278 MPR.........................................................................12 629 NOFLSH...................................................................420 MSG.........................................................................12 630 non-blocking..............................................................82 PIO...........................................................................13 631 non-canonical mode input processing...............216 PS .............................................................................13 632 non-spacing characters............................................82 RTS ..........................................................................13 633 NOSTR......................................................................278 SD.............................................................................13 634 NUL.............................................................................82 SEM .........................................................................13 635 NULL...............................351, 358, 362, 366, 427, 445 SHM ........................................................................13 636 null byte......................................................................83 SIO ...........................................................................13 637 null pointer.................................................................83 SPI............................................................................14 638 null string ...................................................................83 SPN..........................................................................14 639 null wide-character code.........................................83 SS..............................................................................14 640 number sign...............................................................83 TCT..........................................................................14 641 numerical limits......................................................290 TEF...........................................................................15 642 NZERO .....................................................................292 THR .........................................................................14 643 OB ................................................................................12 TMO ........................................................................14 644 object file.....................................................................83 TMR.........................................................................14 645 OCRNL.....................................................................418 TPI............................................................................14 646 octet .............................................................................83 TPP ..........................................................................15 647 OF.................................................................................12 TPS...........................................................................15 648 offset maximum........................................................84 TRC..........................................................................15 649 off_t............................................................................405 TRI ...........................................................................15 650 OFILL ........................................................................418 TRL ..........................................................................15 651 OH ...............................................................................12 TSA..........................................................................15 652 OLD_TIME...............................................................460 TSF...........................................................................16 653 ONLCR.....................................................................418 TSH..........................................................................16 654 ONLRET...................................................................418 TSP...........................................................................16 655 ONOCR ....................................................................418 TSS...........................................................................16 656 opaque address .........................................................84 TYM.........................................................................16 657 open file ......................................................................84 UP ............................................................................16 658 open file description ................................................84 XSR ..........................................................................17 659 OPEN_MAX....................................................282, 335 option-argument.......................................................85 Base Definitions, Issue 6 483 Index 660 options POLLIN ....................................................................320 661 shell and utilities...................................................35 polling .........................................................................88 662 system interfaces ..................................................32 POLLNVAL .............................................................320 663 orientation..................................................................85 POLLOUT ................................................................320 664 orphaned process group .........................................85 POLLPRI...................................................................320 665 output devices.........................................................211 POLLRDBAND.......................................................320 666 O_ constants POLLRDNORM......................................................320 667 defined in ....................................251-252 POLLWRBAND......................................................320 668 O_ACCMODE.........................................................252 POLLWRNORM.....................................................320 669 O_APPEND .............................................................251 POLL_ERR ...............................................................342 670 O_CREAT .................................................................251 POLL_HUP..............................................................342 671 O_DSYNC ................................................................251 POLL_IN ..................................................................342 672 O_EXCL....................................................................251 POLL_MSG..............................................................342 673 O_NOCTTY.............................................................251 POLL_OUT ..............................................................342 674 O_NONBLOCK ......................................................251 POLL_PRI.................................................................342 675 O_RDONLY.............................................................252 portable character set ......................................88, 133 676 O_RDWR..................................................................252 portable file name character set ....................88, 122 677 O_RSYNC ................................................................252 positional parameter................................................88 678 O_SYNC ...................................................................252 POSIX 679 O_TRUNC................................................................251 conformance..........................................................19 680 O_WRONLY............................................................252 POSIX locale ............................................................144 681 page .............................................................................85 POSIX shell and utilities..........................................23 682 page size .....................................................................85 POSIX system interfaces 683 PAGESIZE................................................................282 conformance..........................................................20 684 PAGE_SIZE..............................................................282 POSIX2_CHAR_TERM .....................................23, 35 685 parameter ...................................................................85 POSIX2_C_DEV..................................................23, 35 686 PARENB ...................................................................420 POSIX2_FORT_DEV..........................................23, 35 687 parent directory ........................................................86 POSIX2_FORT_RUN.........................................23, 35 688 parent process ...........................................................86 POSIX2_LOCALEDEF.......................................23, 36 689 parent process ID......................................................86 POSIX2_PBS ........................................................23, 36 690 PARMRK..................................................................418 POSIX2_PBS_ACCOUNTING ........................23, 36 691 PARODD..................................................................420 POSIX2_PBS_CHECKPOINT ................................36 692 PATH.........................................................................192 POSIX2_PBS_LOCATE......................................23, 36 693 path name...................................................................86 POSIX2_PBS_MESSAGE...................................23, 36 694 path name component.............................................86 POSIX2_PBS_TRACK........................................23, 36 695 path name resolution.............................................123 POSIX2_SW_DEV ..............................................23, 36 696 path name variable values....................................284 POSIX2_UPE .......................................................23, 36 697 path prefix..................................................................86 POSIX_ALLOC_SIZE_MIN .................................285 698 PATH_MAX.....................................................285, 293 POSIX_FADV_DONTNEED................................252 699 pattern.........................................................................87 POSIX_FADV_NOREUSE ....................................252 700 period ..........................................................................87 POSIX_FADV_NORMAL.....................................252 701 permissions................................................................87 POSIX_FADV_RANDOM ....................................252 702 persistence..................................................................87 POSIX_FADV_SEQUENTIAL .............................252 703 pid_t ..........................................................................405 POSIX_FADV_WILLNEED..................................252 704 PIO...............................................................................13 POSIX_MADV_DONTNEED ..............................377 705 pipe..............................................................................87 POSIX_MADV_NORMAL ...................................376 706 PIPE_BUF .................................................................285 POSIX_MADV_RANDOM...................................377 707 PM_STR....................................................................278 POSIX_MADV_SEQUENTIAL............................377 708 POLLERR .................................................................320 POSIX_MADV_WILLNEED ................................377 709 pollfd.........................................................................320 POSIX_REC_INCR_XFER_SIZE .........................285 710 POLLHUP ................................................................320 POSIX_REC_MAX_XFER_SIZE..........................285 484 Technical Standard (2000) (Draft July 31, 2000) Index 711 POSIX_REC_MIN_XFER_SIZE ...........................285 PTHREAD_CREATE_DETACHED....................322 712 POSIX_REC_XFER_ALIGN .................................285 PTHREAD_CREATE_JOINABLE .......................322 713 POSIX_TYPED_MEM_ALLOCATE ...................377 PTHREAD_DESTRUCTOR_ITERATIONS ......283 714 POSIX_TYPED_MEM_ALLOCATE_CONTIG 377 PTHREAD_EXPLICIT_SCHED...........................322 715 POSIX_TYPED_MEM_MAP_ALLOCATABLE377 PTHREAD_INHERIT_SCHED............................322 716 preallocation..............................................................88 PTHREAD_KEYS_MAX .......................................283 717 preempted process (or thread) ..............................89 PTHREAD_MUTEX_DEFAULT..........................322 718 printable character....................................................89 PTHREAD_MUTEX_ERRORCHECK ...............322 719 printable file...............................................................89 PTHREAD_MUTEX_INITIALIZER ...................322 720 priority ........................................................................89 PTHREAD_MUTEX_NORMAL .........................322 721 priority band..............................................................89 PTHREAD_MUTEX_RECURSIVE .....................322 722 priority inversion......................................................90 PTHREAD_ONCE_INIT ......................................322 723 priority scheduling...................................................90 PTHREAD_PRIO_INHERIT................................322 724 priority-based scheduling.......................................90 PTHREAD_PRIO_NONE.....................................322 725 PRIO_ constants PTHREAD_PRIO_PROTECT ..............................322 726 defined in ............................381 PTHREAD_PROCESS_PRIVATE........................322 727 PRIO_PGRP.............................................................381 PTHREAD_PROCESS_SHARED........................322 728 PRIO_PROCESS......................................................381 PTHREAD_RWLOCK_INITIALIZER ...............322 729 PRIO_USER .............................................................381 PTHREAD_SCOPE_PROCESS............................322 730 privilege......................................................................90 PTHREAD_SCOPE_SYSTEM..............................322 731 process ........................................................................90 PTHREAD_STACK_MIN .....................................283 732 process group ............................................................90 PTHREAD_THREADS_MAX..............................283 733 process group ID.......................................................91 PWD ..........................................................................193 734 process group leader................................................91 P_ALL .......................................................................411 735 process group lifetime.............................................91 P_GID........................................................................411 736 process groups P_PID ........................................................................411 737 termios..................................................................213 P_tmpdir...................................................................358 738 process ID...................................................................91 radix character...........................................................93 739 process lifetime .........................................................91 RADIXCHAR ..........................................................278 740 process memory locking .........................................92 RAND_MAX ...........................................................362 741 process termination..................................................92 read-only file system................................................93 742 process virtual time..................................................92 read-write lock ..........................................................93 743 process-to-process communication......................92 real group ID..............................................................93 744 profiling option groups...........................................25 real time......................................................................93 745 program ......................................................................92 real user ID.................................................................94 746 protocol.......................................................................92 realtime.......................................................................27 747 PROT_EXEC ............................................................376 REALTIME ......................................232, 306, 331, 335 748 PROT_NONE..........................................................376 realtime signal extension ........................................94 749 PROT_READ ...........................................................376 realtime threads ........................................................29 750 PROT_READ constants record ..........................................................................94 751 in ...............................................376 redirection ..................................................................94 752 PROT_WRITE .........................................................376 redirection operator .................................................94 753 PS..................................................................................13 reentrant function.....................................................94 754 pseudo-terminal........................................................93 referenced shared memory object.........................95 755 PTHREAD_BARRIER_SERIAL_THREAD .......322 refresh .........................................................................95 756 PTHREAD_CANCELED ......................................322 region ..........................................................................95 757 PTHREAD_CANCEL_ASYNCHRONOUS .....322 REGTYPE .................................................................415 758 PTHREAD_CANCEL_DEFERRED ....................322 regular expression ....................................................95 759 PTHREAD_CANCEL_DISABLE ........................322 basic.......................................................................198 760 PTHREAD_CANCEL_ENABLE .........................322 extended...............................................................203 761 PTHREAD_COND_INITIALIZER .....................322 grammar...............................................................206 Base Definitions, Issue 6 485 Index 762 regular file ..................................................................95 RTLD_NOW............................................................246 763 REG_ constants RTS...............................................................................13 764 defined in ..........................................329 RTSIG_MAX....................................................283, 339 765 REG_BADBR ...........................................................329 runnable process (or thread) ..................................96 766 REG_BADPAT.........................................................329 running process (or thread)....................................96 767 REG_BADRPT.........................................................330 runtime values 768 REG_EBRACE.........................................................329 increasable ...........................................................285 769 REG_EBRACK.........................................................329 invariant ...............................................................281 770 REG_ECOLLATE....................................................329 rusage........................................................................381 771 REG_ECTYPE..........................................................329 RUSAGE_CHILDREN...........................................381 772 REG_EESCAPE .......................................................329 RUSAGE_SELF .......................................................381 773 REG_ENOSYS.........................................................330 R_OK.........................................................................445 774 REG_EPAREN.........................................................329 saved resource limits ...............................................96 775 REG_ERANGE........................................................330 saved set-group-ID...................................................97 776 REG_ESPACE..........................................................330 saved set-user-ID......................................................97 777 REG_ESUBREG.......................................................329 SA_ constants 778 REG_EXTENDED...................................................329 declared in .......................................340 779 REG_ICASE .............................................................329 SA_NOCLDSTOP...................................................340 780 REG_NEWLINE .....................................................329 SA_NOCLDWAIT..................................................340 781 REG_NOMATCH...................................................329 SA_NODEFER.........................................................340 782 REG_NOSUB...........................................................329 SA_ONSTACK ........................................................340 783 REG_NOTBOL........................................................329 SA_RESETHAND...................................................340 784 REG_NOTEOL........................................................329 SA_RESTART ..........................................................340 785 relative path name ...........................................95, 123 SA_SIGINFO ...........................................................340 786 relocatable file ...........................................................95 SCHAR_MAX .........................................................291 787 relocation....................................................................96 SCHAR_MIN...................................................291-292 788 requested batch service ...........................................96 scheduling..................................................................97 789 requirements..............................................................19 scheduling allocation domain................................97 790 RE_DUP_MAX................................................283, 286 scheduling contention scope..................................97 791 rlimit..........................................................................381 scheduling policy......................................................97 792 RLIMIT_AS..............................................................382 SCHED_FIFO ..........................................................331 793 RLIMIT_CORE........................................................381 SCHED_OTHER.....................................................331 794 RLIMIT_CPU...........................................................381 SCHED_RR..............................................................331 795 RLIMIT_DATA........................................................381 SCHED_SPORADIC ..............................................331 796 RLIMIT_FSIZE ........................................................381 SCM_RIGHTS .........................................................390 797 RLIMIT_NOFILE....................................................382 screen...........................................................................98 798 RLIMIT_STACK......................................................382 scroll ............................................................................98 799 RLIM_INFINITY.....................................................381 SD.................................................................................13 800 RLIM_SAVED_CUR...............................................381 SEEK_CUR ..............................................251, 358, 448 801 RLIM_SAVED_MAX..............................................381 SEEK_END..............................................251, 358, 448 802 RMSGD.....................................................................371 SEEK_SET................................................251, 358, 448 803 RMSGN.....................................................................371 SEGV_ACCERR......................................................342 804 RNORM....................................................................371 SEGV_MAPERR .....................................................342 805 root directory.............................................................96 SEM..............................................................................13 806 RPROTDAT..............................................................371 semaphore..................................................................98 807 RPROTDIS ...............................................................371 SEM_NSEMS_MAX ...............................................283 808 RPROTNORM.........................................................371 SEM_UNDO ............................................................385 809 RS_HIPRI .................................................................371 SEM_VALUE_MAX ...............................................283 810 RTLD_GLOBAL......................................................246 session.........................................................................98 811 RTLD_LAZY............................................................246 session leader.............................................................98 812 RTLD_LOCAL ........................................................246 session lifetime..........................................................99 486 Technical Standard (2000) (Draft July 31, 2000) Index 813 SETALL.....................................................................385 SIGUSR1...................................................................339 814 SETVAL ....................................................................385 SIGUSR2...................................................................339 815 shall................................................................................8 SIGVTALRM............................................................339 816 shared memory object .............................................99 SIGXCPU..................................................................339 817 shared memory objects............................................78 SIGXFSZ ...................................................................339 818 shell..............................................................................99 SIG_BLOCK.............................................................340 819 SHELL.......................................................................193 SIG_DFL ...................................................................338 820 shell script ..................................................................99 SIG_ERR ...................................................................338 821 shell, the......................................................................99 SIG_HOLD...............................................................338 822 SHM.............................................................................13 SIG_IGN ...................................................................338 823 SHM_RDONLY.......................................................387 SIG_SETMASK........................................................340 824 SHM_RND...............................................................387 SIG_UNBLOCK ......................................................340 825 should............................................................................8 single-quote .............................................................100 826 SHRT_MAX.............................................................291 SIO ...............................................................................13 827 SHRT_MIN ..............................................................292 size_t .................................................................366, 405 828 SHUT_RD.................................................................391 SI_ASYNCIO...........................................................342 829 SHUT_RDWR..........................................................392 SI_MESGQ ...............................................................342 830 SHUT_WR................................................................391 SI_QUEUE................................................................342 831 SIGABRT ..................................................................339 SI_TIMER .................................................................342 832 SIGALRM.................................................................339 SI_USER....................................................................342 833 SIGBUS .............................................................339, 342 slash...........................................................................100 834 SIGCHLD.........................................................339, 342 SNDZERO................................................................371 835 SIGCONT.................................................................339 socket ........................................................................100 836 SIGEV_NONE.........................................................338 socket address .........................................................100 837 SIGEV_SIGNAL......................................................338 SOCK_DGRAM ......................................................390 838 SIGEV_THREAD....................................................338 SOCK_SEQPACKET..............................................390 839 SIGFPE..............................................................339, 342 SOCK_STREAM .....................................................390 840 SIGHUP ....................................................................339 soft limit....................................................................100 841 SIGILL...............................................................339, 342 SOL_SOCKET .........................................................390 842 siginfo_t....................................................................341 SOMAXCONN .......................................................391 843 SIGINT......................................................................339 source code ..............................................................100 844 SIGKILL....................................................................339 SO_ACCEPTCONN ..............................................390 845 signal ...........................................................................99 SO_BROADCAST...................................................390 846 signal stack...............................................................100 SO_DEBUG..............................................................391 847 SIGPIPE ....................................................................339 SO_DONTROUTE..................................................391 848 SIGPOLL..................................................339, 342, 370 SO_ERROR ..............................................................391 849 SIGPROF ..................................................................339 SO_KEEPALIVE......................................................391 850 SIGQUEUE_MAX...................................................283 SO_LINGER.............................................................391 851 SIGQUIT...................................................................339 SO_OOBINLINE.....................................................391 852 SIGRTMAX..............................................................338 SO_RCVBUF............................................................391 853 SIGRTMIN ...............................................................338 SO_RCVLOWAT.....................................................391 854 SIGSEGV ..........................................................339, 342 SO_RCVTIMEO......................................................391 855 SIGSTKSZ.................................................................340 SO_REUSEADDR...................................................391 856 SIGSTOP...................................................................339 SO_SNDBUF............................................................391 857 SIGSYS ......................................................................339 SO_SNDLOWAT ....................................................391 858 SIGTERM..................................................................339 SO_SNDTIMEO......................................................391 859 SIGTRAP..........................................................339, 342 SO_TYPE ..................................................................391 860 SIGTSTP ...................................................................339 space character........................................................101 861 SIGTTIN ...................................................................339 spawn........................................................................101 862 SIGTTOU..................................................................339 special built-in.........................................................101 863 SIGURG ....................................................................339 special parameter ...................................................101 Base Definitions, Issue 6 487 Index 864 SPI ................................................................................14 synchronized I/O file integrity completion......105 865 spin lock....................................................................101 synchronized I/O operation ................................105 866 SPN..............................................................................14 synchronized input and output...........................104 867 sporadic server........................................................101 synchronous I/O operation .................................105 868 SS..................................................................................14 synchronously-generated signal .........................105 869 SSIZE_MAX.....................................................291, 406 system .......................................................................105 870 ssize_t........................................................................405 system console ........................................................106 871 SS_DISABLE ............................................................340 system crash ............................................................105 872 SS_ONSTACK .........................................................340 system databases....................................................106 873 SS_REPL_MAX .......................................................283 system documentation..........................................106 874 stack_t .......................................................................340 system process ........................................................106 875 standard error..........................................................101 system reboot ..........................................................107 876 standard input.........................................................102 system-wide.............................................................107 877 standard output ......................................................102 S_ constants 878 standard utilities.....................................................102 defined in .............................394-395 879 stat data structure...................................................394 S_ macros 880 stderr .........................................................................358 defined in .....................................395 881 STDERR_FILENO ..................................................452 S_BANDURG ..........................................................371 882 stdin...........................................................................358 S_ERROR..................................................................371 883 STDIN_FILENO......................................................452 S_HANGUP.............................................................371 884 stdout ........................................................................358 S_HIPRI ....................................................................370 885 STDOUT_FILENO .................................................452 S_IFBLK ....................................................................394 886 strbuf .........................................................................369 S_IFCHR...................................................................394 887 STREAM...................................................................102 S_IFDIR.....................................................................395 888 stream........................................................................102 S_IFIFO .....................................................................395 889 STREAM...................................................................248 S_IFLNK ...................................................................395 890 STREAM end...........................................................103 S_IFMT......................................................................394 891 STREAM head.........................................................103 S_IFREG....................................................................395 892 STREAMS...........................................................31, 369 S_IFSOCK.................................................................395 893 STREAMS multiplexor..........................................103 S_INPUT...................................................................370 894 STREAM_MAX.......................................................283 S_IRGRP ...................................................................395 895 strfdinsert.................................................................369 S_IROTH ..................................................................395 896 string .........................................................................103 S_IRUSR ...................................................................395 897 strioctl .......................................................................369 S_IRWXG .................................................................395 898 strpeek.......................................................................369 S_IRWXO .................................................................395 899 strrecvfd....................................................................369 S_IRWXU .................................................................395 900 str_list........................................................................369 S_ISBLK ....................................................................395 901 str_mlist....................................................................370 S_ISCHR...................................................................395 902 ST_NOSUID ............................................................399 S_ISDIR.....................................................................395 903 ST_RDONLY ...........................................................399 S_ISFIFO...................................................................396 904 subshell.....................................................................103 S_ISGID.............................................................395-396 905 successfully transferred ........................................103 S_ISLNK ...................................................................396 906 supplementary group ID ......................................104 S_ISREG....................................................................396 907 suseconds_t..............................................................405 S_ISSOCK.................................................................396 908 suspended job..........................................................104 S_ISUID.............................................................395-396 909 symbolic link ...........................................................104 S_ISVTX....................................................................395 910 SYMLINK_MAX.............................................285, 293 S_IWGRP..................................................................395 911 SYMLOOP_MAX....................................................283 S_IWOTH.................................................................395 912 SYMTYPE.................................................................415 S_IWUSR..................................................................395 913 synchronized I/O completion .............................104 S_IXGRP ...................................................................395 914 synchronized I/O data integrity completion ...104 S_IXOTH ..................................................................395 488 Technical Standard (2000) (Draft July 31, 2000) Index 915 S_IXUSR ...................................................................395 thread list..................................................................108 916 S_MSG.......................................................................371 thread-safe ...............................................................109 917 S_OUTPUT ..............................................................370 thread-specific data key ........................................109 918 S_RDBAND .............................................................370 tilde............................................................................109 919 S_RDNORM ............................................................370 timeb..........................................................................403 920 S_TYPEISMQ...........................................................396 timeouts....................................................................109 921 S_TYPEISSEM .........................................................396 timer ..........................................................................109 922 S_TYPEISSHM ........................................................396 timer overrun ..........................................................109 923 S_TYPEISTMO........................................................396 TIMER_ABSTIME...................................................427 924 S_WRBAND ............................................................370 TIMER_MAX...........................................................283 925 S_WRNORM ...........................................................370 timer_t.......................................................................405 926 tab character ............................................................107 timeval ......................................................................401 927 TABDLY....................................................................418 time_t ........................................................................405 928 TABn..........................................................................418 TMAGIC...................................................................415 929 TCIFLUSH ...............................................................421 TMAGLEN...............................................................415 930 TCIOFF .....................................................................421 TMO ............................................................................14 931 TCIOFLUSH ............................................................421 TMPDIR....................................................................193 932 TCION ......................................................................421 TMP_MAX.......................................................293, 358 933 TCOFLUSH..............................................................421 TMR.............................................................................14 934 TCOOFF ...................................................................421 TOEXEC ...................................................................415 935 TCOON ....................................................................421 token..........................................................................110 936 TCP_NODELAY .....................................................318 TOREAD...................................................................415 937 TCSADRAIN...........................................................420 TOSTOP....................................................................420 938 TCSAFLUSH ...........................................................420 TOWRITE.................................................................415 939 TCSANOW ..............................................................420 TPI................................................................................14 940 TCT ..............................................................................14 TPP...............................................................................15 941 TEF...............................................................................15 TPS...............................................................................15 942 TERM ........................................................................193 TRAP_BRKPT..........................................................342 943 terminal TRAP_TRACE.........................................................342 944 controlling............................................................214 TRC..............................................................................15 945 terminal (or terminal device) ...............................107 TRI ...............................................................................15 946 terminal types..........................................................211 TRL ..............................................................................15 947 termios ......................................................................213 TSA ..............................................................................15 948 canonical mode input processing ...................215 TSF ...............................................................................16 949 control modes......................................................222 TSGID........................................................................415 950 controlling terminal ...........................................214 TSH..............................................................................16 951 input modes.........................................................219 TSP...............................................................................16 952 local modes..........................................................223 TSS ...............................................................................16 953 non-canonical mode input processing...........216 TSUID........................................................................415 954 output modes......................................................220 TSVTX.......................................................................415 955 process groups....................................................213 TTY_NAME_MAX.................................................284 956 special control characters .................................224 TUEXEC....................................................................415 957 text column ..............................................................108 TUREAD...................................................................415 958 text file ......................................................................108 TUWRITE.................................................................415 959 TGEXEC....................................................................415 TVERSION...............................................................415 960 TGREAD...................................................................415 TVERSLEN...............................................................415 961 TGWRITE.................................................................415 TYM.............................................................................16 962 THOUSEP ................................................................278 typed memory name space ..................................113 963 THR .............................................................................14 typed memory object.............................................114 964 thread ........................................................................108 typed memory pool................................................114 965 thread ID...................................................................108 typed memory port ................................................114 Base Definitions, Issue 6 489 Index 966 TZ...............................................................................193 WEXITSTATUS...............................................362, 411 967 TZNAME_MAX......................................................284 white space ..............................................................116 968 T_FMT.......................................................................278 wide characters .......................................................137 969 T_FMT_AMPM.......................................................278 wide-character code (C language) ......................116 970 t_uscalar_t................................................................369 wide-character input/output functions ............116 971 UCHAR_MAX ........................................................291 wide-character string.............................................116 972 ucontext_t.................................................................435 WIFCONTINUED..................................................411 973 uid_t ..........................................................................405 WIFEXITED.....................................................362, 411 974 UINT_MAX .............................................................291 WIFSIGNALED ..............................................362, 411 975 ULONG_MAX ........................................................291 WIFSTOPPED .................................................362, 411 976 UL_GETFSIZE.........................................................436 WNOHANG ...................................................362, 411 977 UL_SETFSIZE..........................................................436 WNOWAIT..............................................................411 978 UN................................................................................16 word ..........................................................................117 979 unbind.......................................................................114 WORD_BIT ......................................................290-291 980 undefined .....................................................................8 working directory...................................................117 981 unspecified...................................................................9 worldwide portability interface ..........................117 982 UP.................................................................................16 WRDE_APPEND....................................................468 983 upper multiplexing ................................................103 WRDE_BADCHAR................................................468 984 upshifting.................................................................114 WRDE_BADVAL....................................................468 985 user database...........................................................114 WRDE_CMDSUB ...................................................468 986 user ID.......................................................................115 WRDE_DOOFFS.....................................................468 987 user name.................................................................115 WRDE_NOCMD ....................................................468 988 USER_PROCESS.....................................................460 WRDE_NOSPACE .................................................468 989 USHRT_MAX..........................................................291 WRDE_NOSYS .......................................................468 990 utility.........................................................................115 WRDE_REUSE ........................................................468 991 Utility Syntax Guidelines......................................229 WRDE_SHOWERR................................................468 992 utmpx........................................................................460 WRDE_SYNTAX.....................................................468 993 variable .....................................................................115 WRDE_UNDEF.......................................................468 994 VEOF.........................................................................417 write ..........................................................................117 995 VEOL.........................................................................417 WSTOPPED .............................................................411 996 VERASE....................................................................417 WSTOPSIG ......................................................362, 411 997 vertical-tab character .............................................116 WTERMSIG.....................................................362, 411 998 VFS.............................................................................399 WUNTRACED................................................362, 411 999 VINTR.......................................................................417 W_OK........................................................................445 1000 VKILL........................................................................417 XSI........................................................................16, 117 1001 VQUIT.......................................................................417 conformance..........................................................19 1002 VSTART ....................................................................417 XSI conformance.......................................................23 1003 VSTOP.......................................................................417 XSI options groups...................................................27 1004 VSUSP .......................................................................417 XSI STREAMS ...........................................................31 1005 VTDLY ......................................................................419 XSI system interfaces 1006 VTn ............................................................................419 conformance..........................................................23 1007 warning XSI-conformant.......................................................117 1008 MAN .......................................................................11 XSR ..............................................................................17 1009 OB ............................................................................12 X_OK.........................................................................445 1010 OF ............................................................................12 YESEXPR..................................................................278 1011 UN ...........................................................................16 YESSTR.....................................................................278 1012 WCHAR_MAX .......................................................464 zombie process........................................................118 1013 WCHAR_MIN.........................................................464 1014 WCONTINUED......................................................411 1015 WEOF .......................................................462, 464, 466 1016 WEXITED.................................................................411 490 Technical Standard (2000) (Draft July 31, 2000) ||||||||||| Chapter 1 | 1 Introduction | 2 1.1 Scope 3 The scope of IEEE Std. 1003.1-200x is described in the Base Definitions volume of | 4 IEEE Std. 1003.1-200x. | 5 1.2 Conformance 6 Conformance requirements for IEEE Std. 1003.1-200x are defined in the Base Definitions volume | 7 of IEEE Std. 1003.1-200x, Chapter 2, Conformance. | 8 1.3 Normative References 9 Normative references for IEEE Std. 1003.1-200x are defined in the Base Definitions volume of | 10 IEEE Std. 1003.1-200x. | 11 1.4 Changes from Issue 4 12 Notes to Reviewers | 13 This section with side shading will not appear in the final copy. - Ed. 14 The change history is subject to revision. The intent is to document changes from Issue 4 thru 15 Issue 6, with the latest change history also documenting changes from the ISO POSIX-1: 1996 16 standard. 17 The following sections describe changes made to this volume of IEEE Std. 1003.1-200x since 18 Issue 4. The CHANGE HISTORY section for each entry details the technical changes that have 19 been made to that entry since Issue 4. Changes made between Issue 2 and Issue 4 are not 20 included. 21 1.4.1 Changes from Issue 4 to Issue 4, Version 2 22 The following list summarizes the major changes that were made in this volume of 23 IEEE Std. 1003.1-200x from Issue 4 to Issue 4, Version 2: 24 * The X/Open UNIX extension was added. This specifies the common core APIs of 4.3 25 Berkeley Software Distribution (BSD 4.3), the OSF AES, and SVID Issue 3. 26 * STREAMS were added as part of the X/Open UNIX extension. 27 * Existing Issue 4 functions were clarified as a result of industry feedback. System Interfaces, Issue 6 491 Changes from Issue 4 Introduction 28 1.4.2 Changes from Issue 4, Version 2 to Issue 5 29 The following list summarizes the major changes that were made in this volume of 30 IEEE Std. 1003.1-200x from Issue 4, Version 2 to Issue 5: 31 * Functions previously defined in the ISO POSIX-2 standard C-language Binding, Shared 32 Memory, Enhanced Internationalization, and X/Open UNIX Extension Feature Groups were 33 moved to the BASE. 34 * Threads were added to the BASE for alignment with the POSIX Threads Extension. 35 * The Realtime Threads Feature Group was added. 36 * The Realtime Feature Group was added for alignment with the POSIX Realtime Extension. 37 * Multibyte Support Extensions (MSE) were added to the BASE for alignment with 38 ISO/IEC 9899: 1990/Amendment 1: 1995 (E). 39 * Large File Summit (LFS) Extensions were added to the BASE for support of 64-bit or larger 40 files and file systems. 41 * X/Open-specific threads extensions were added to the BASE. 42 * X/Open-specific dynamic linking functions were added to the BASE. 43 * A new category Legacy was added. 44 * The categories TO BE WITHDRAWN and WITHDRAWN were removed. 45 1.4.3 Changes from Issue 5 to Issue 6 (IEEE Std. 1003.1-200x) 46 The following list summarizes the major changes that were made in this volume of 47 IEEE Std. 1003.1-200x from Issue 5 to Issue 6: 48 * This volume of IEEE Std. 1003.1-200x is extensively revised so it can be both an IEEE POSIX 49 Standard and an Open Group Technical Standard. 50 * The POSIX System Interfaces requirements incorporate support of FIPS 151-2. 51 * The POSIX System Interfaces requirements are updated to align with some features of the 52 Single UNIX Specification. 53 * A RATIONALE section is added to each reference page. | 492 Technical Standard (2000) (Draft July 31, 2000) Introduction New Features 54 1.5 New Features 55 1.5.1 New Features in Issue 4, Version 2 56 The functions, headers, and external variables first introduced in Issue 4, Version 2 are listed in 57 the table below. 58 _________________________________________________________________________________ 59 _ New Functions, Headers, and External Variables in Issue 4, Version 2 ________________________________________________________________________________ 60 FD_CLR( ) endutxent( ) gettimeofday( ) ptsname( ) sigaltstack( ) 61 FD_ISSET( ) expm1( ) getutxent( ) putmsg( ) sighold( ) 62 FD_SET( ) fattach( ) getutxid( ) putpmsg( ) sigignore( ) 63 FD_ZERO( ) fchdir( ) getutxline( ) pututxline( ) siginterrupt( ) 64 _longjmp( ) fchmod( ) getwd( ) random( ) sigpause( ) 65 _setjmp( ) fchown( ) grantpt( ) re_comp( ) sigrelse( ) 66 a64l( ) fcvt( ) ilogb( ) re_exec( ) sigset( ) 67 acosh( ) fdetach( ) index( ) readlink( ) sigstack( ) 68 asinh( ) ffs( ) initstate( ) readv( ) srandom( ) 69 atanh( ) fmtmsg( ) insque( ) realpath( ) statvfs( ) 70 basename( ) fstatvfs( ) ioctl( ) regcmp( ) strcasecmp( ) 71 bcmp( ) ftime( ) isastream( ) regex( ) strdup( ) 72 bcopy( ) ftok( ) killpg( ) remainder( ) strncasecmp( ) 73 brk( ) ftruncate( ) l64a( ) remque( ) swapcontext( ) 74 bsd_signal( ) gcvt( ) lchown( ) rindex( ) symlink( ) 75 bzero( ) getcontext( ) lockf( ) rint( ) sync( ) 76 cbrt( ) getdate( ) log1p( ) sbrk( ) syslog( ) 77 closelog() getdtablesize( ) logb( ) scalb( ) tcgetsid( ) 78 dbm_clearerr( ) getgrent( ) lstat( ) select( ) truncate( ) 79 dbm_close( ) gethostid( ) makecontext( ) setcontext( ) ttyslot( ) 80 dbm_delete( ) getitimer( ) mknod( ) setgrent( ) ualarm( ) 81 dbm_error( ) getmsg( ) mkstemp( ) setitimer( ) unlockpt( ) 82 dbm_fetch( ) getpagesize( ) mktemp( ) setlogmask( ) usleep( ) 83 dbm_firstkey( ) getpgid( ) mmap( ) setpgrp( ) utimes( ) 84 dbm_nextkey( ) getpmsg( ) mprotect( ) setpriority( ) valloc( ) 85 dbm_open( ) getpriority( ) msync( ) setpwent( ) vfork( ) 86 dbm_store( ) getpwent( ) munmap( ) setregid( ) wait3( ) 87 dirname( ) getrlimit( ) nextafter( ) setreuid( ) waitid( ) 88 ecvt( ) getrusage( ) nftw( ) setrlimit( ) writev( ) 89 endgrent( ) getsid( ) openlog( ) setstate( ) 90 endpwent( ) getsubopt( ) poll( ) setutxent( ) 91 92 93 94 95 _ getdate_err _ _loc1 ________________________________________________________________________________ System Interfaces, Issue 6 493 New Features Introduction 96 1.5.2 New Features in Issue 5 97 The functions and headers first introduced in Issue 5 are listed in the table below. 98 _______________________________________________________________________________ 99 _ New Functions and Headers in Issue 5 ______________________________________________________________________________ 100 aio_cancel( ) pthread_attr_getstacksize( ) pthread_self( ) 101 aio_error( ) pthread_attr_init( ) pthread_setcancelstate( ) 102 aio_fsync( ) pthread_attr_setdetachstate( ) pthread_setcanceltype( ) 103 aio_read( ) pthread_attr_setguardsize( ) pthread_setconcurrency( ) 104 aio_return( ) pthread_attr_setinheritsched( ) pthread_setschedparam( ) 105 aio_suspend( ) pthread_attr_setschedparam( ) pthread_setspecific( ) 106 aio_write( ) pthread_attr_setschedpolicy( ) pthread_sigmask( ) 107 asctime_r( ) pthread_attr_setscope( ) pthread_testcancel( ) 108 btowc( ) pthread_attr_setstackaddr( ) putc_unlocked( ) 109 clock_getres( ) pthread_attr_setstacksize( ) putchar_unlocked( ) 110 clock_gettime( ) pthread_cancel( ) pwrite( ) 111 clock_settime( ) pthread_cleanup_pop( ) rand_r( ) 112 ctime_r( ) pthread_cleanup_push( ) readdir_r( ) 113 dlclose( ) pthread_cond_broadcast( ) sched_get_priority_max( ) 114 dlerror( ) pthread_cond_destroy( ) sched_get_priority_min( ) 115 dlopen( ) pthread_cond_init( ) sched_getparam( ) 116 dlsym( ) pthread_cond_signal( ) sched_getscheduler( ) 117 fdatasync() pthread_cond_timedwait( ) sched_rr_get_interval( ) 118 flockfile ( ) pthread_cond_wait( ) sched_setparam( ) 119 fseeko( ) pthread_condattr_destroy( ) sched_setscheduler( ) 120 ftello( ) pthread_condattr_getpshared( ) sched_yield( ) 121 ftrylockfile( ) pthread_condattr_init( ) sem_close( ) 122 funlockfile( ) pthread_condattr_setpshared( ) sem_destroy( ) 123 fwide( ) pthread_create( ) sem_getvalue( ) 124 fwprintf( ) pthread_detach( ) sem_init( ) 125 fwscanf( ) pthread_equal( ) sem_open( ) 126 getc_unlocked( ) pthread_exit( ) sem_post( ) 127 getchar_unlocked( ) pthread_getconcurrency( ) sem_trywait( ) 128 getgrgid_r( ) pthread_getschedparam( ) sem_unlink( ) 129 getgrnam_r( ) pthread_getspecific( ) sem_wait( ) 130 getlogin_r( ) pthread_join( ) shm_open( ) 131 getpwnam_r( ) pthread_key_create( ) shm_unlink( ) 132 getpwuid_r( ) pthread_key_delete( ) sigqueue( ) 133 gmtime_r( ) pthread_kill ( ) sigtimedwait( ) 134 lio_listio ( ) pthread_mutex_destroy( ) sigwait( ) 135 localtime_r( ) pthread_mutex_getprioceiling( ) sigwaitinfo ( ) 136 mbrlen( ) pthread_mutex_init( ) snprintf( ) 137 mbrtowc( ) pthread_mutex_lock( ) strtok_r( ) 138 mbsinit() pthread_mutex_setprioceiling( ) swprintf( ) 139 mbsrtowcs( ) pthread_mutex_trylock( ) swscanf( ) 140 mlock( ) pthread_mutex_unlock( ) timer_create( ) 141 mlockall( ) pthread_mutexattr_destroy( ) timer_delete( ) 142 mq_close( ) pthread_mutexattr_getprioceiling( ) timer_getoverrun( ) 143 mq_getattr( ) pthread_mutexattr_getprotocol( ) timer_gettime( ) 144 mq_notify( ) pthread_mutexattr_getpshared( ) timer_settime( ) 145 mq_open( ) pthread_mutexattr_gettype( ) towctrans( ) _ ______________________________________________________________________________ 494 Technical Standard (2000) (Draft July 31, 2000) Introduction New Features 146 _______________________________________________________________________________ 147 _ New Functions and Headers in Issue 5 ______________________________________________________________________________ 148 mq_receive( ) pthread_mutexattr_init( ) ttyname_r( ) 149 mq_send( ) pthread_mutexattr_setprioceiling( ) vfwprintf( ) 150 mq_setattr( ) pthread_mutexattr_setprotocol( ) vsnprintf( ) 151 mq_unlink( ) pthread_mutexattr_setpshared( ) vswprintf( ) 152 munlock( ) pthread_mutexattr_settype( ) vwprintf( ) 153 munlockall( ) pthread_once( ) wcrtomb( ) 154 nanosleep( ) pthread_rwlock_destroy( ) wcsrtombs( ) 155 pread( ) pthread_rwlock_init( ) wcsstr( ) 156 pthread_atfork( ) pthread_rwlock_rdlock( ) wctob( ) 157 pthread_attr_destroy( ) pthread_rwlock_tryrdlock( ) wctrans( ) 158 pthread_attr_getdetachstate( ) pthread_rwlock_trywrlock( ) wmemchr( ) 159 pthread_attr_getguardsize( ) pthread_rwlock_unlock( ) wmemcmp( ) 160 pthread_attr_getinheritsched( ) pthread_rwlock_wrlock( ) wmemcpy( ) 161 pthread_attr_getschedparam( ) pthread_rwlockattr_destroy( ) wmemmove( ) 162 pthread_attr_getschedpolicy( ) pthread_rwlockattr_getpshared( ) wmemset( ) 163 pthread_attr_getscope( ) pthread_rwlockattr_init( ) wprintf( ) 164 pthread_attr_getstackaddr( ) pthread_rwlockattr_setpshared( ) wscanf( ) 165 166 167 _ ______________________________________________________________________________ System Interfaces, Issue 6 495 New Features Introduction 168 1.5.3 New Features in Issue 6 169 Notes to Reviewers 170 This section with side shading will not appear in the final copy. - Ed. 171 A table listing new functions, headers, etc. since the ISO POSIX-1: 1996 standard will be added 172 here in a future draft. 496 Technical Standard (2000) (Draft July 31, 2000) Introduction Terminology 173 1.6 Terminology 174 This section appears in the Base Definitions volume of IEEE Std. 1003.1-200x, but is repeated 175 here for convenience: 176 For the purposes of IEEE Std. 1003.1-200x, the following terminology definitions apply: 177 can 178 Describes a permissible optional feature or behavior available to the user or application. The 179 feature or behavior is mandatory for an implementation that conforms to 180 IEEE Std. 1003.1-200x. An application can rely on the existence of the feature or behavior. 181 implementation-defined 182 Describes a value or behavior that is not defined by IEEE Std. 1003.1-200x but is selected by 183 an implementor. The value or behavior may vary among implementations that conform to 184 IEEE Std. 1003.1-200x. An application should not rely on the existence of the value or 185 behavior. An application that relies on such a value or behavior cannot be assured to be 186 portable across conforming implementations. 187 The implementor shall document such a value or behavior so that it can be used correctly 188 by an application. 189 legacy 190 Describes a feature or behavior that is being retained for compatibility with older 191 applications, but which has limitations which make it inappropriate for developing portable 192 applications. New applications should use alternative means of obtaining equivalent 193 functionality. 194 may 195 Describes a feature or behavior that is optional for an implementation that conforms to 196 IEEE Std. 1003.1-200x. An application should not rely on the existence of the feature or 197 behavior. An application that relies on such a feature or behavior cannot be assured to be 198 portable across conforming implementations. 199 To avoid ambiguity, the opposite of may is expressed as need not, instead of may not. 200 shall 201 For an implementation that conforms to IEEE Std. 1003.1-200x, describes a feature or 202 behavior that is mandatory. An application can rely on the existence of the feature or 203 behavior. 204 For an application or user, describes a behavior that is mandatory. 205 should 206 For an implementation that conforms to IEEE Std. 1003.1-200x, describes a feature or 207 behavior that is recommended but not mandatory. An application should not rely on the 208 existence of the feature or behavior. An application that relies on such a feature or behavior 209 cannot be assured to be portable across conforming implementations. 210 For an application, describes a feature or behavior that is recommended programming 211 practice for optimum portability. 212 undefined 213 Describes the nature of a value or behavior not defined by IEEE Std. 1003.1-200x which 214 results from use of an invalid program construct or invalid data input. 215 The value or behavior may vary among implementations that conform to 216 IEEE Std. 1003.1-200x. An application should not rely on the existence or validity of the 217 value or behavior. An application that relies on any particular value or behavior cannot be System Interfaces, Issue 6 497 Terminology Introduction 218 assured to be portable across conforming implementations. 219 unspecified 220 Describes the nature of a value or behavior not specified by IEEE Std. 1003.1-200x which 221 results from use of a valid program construct or valid data input. 222 The value or behavior may vary among implementations that conform to 223 IEEE Std. 1003.1-200x. An application should not rely on the existence or validity of the 224 value or behavior. An application that relies on any particular value or behavior cannot be 225 assured to be portable across conforming implementations. 498 Technical Standard (2000) (Draft July 31, 2000) Introduction Definitions 226 1.7 Definitions 227 Concepts and definitions are defined in the Base Definitions volume of IEEE Std. 1003.1-200x. System Interfaces, Issue 6 499 Relationship to Other Formal Standards Introduction 228 1.8 Relationship to Other Formal Standards 229 Great care has been taken to ensure that this volume of IEEE Std. 1003.1-200x is fully aligned 230 with the following standards: 231 ISO C (1999) 232 ISO/IEC 9899: 1999, Programming Languages - C. 233 Parts of the ISO/IEC 9899: 1999 standard (hereinafter referred to as the ISO C standard) are 234 referenced to describe requirements also mandated by this volume of IEEE Std. 1003.1-200x. 235 Some functions and headers included within this volume of IEEE Std. 1003.1-200x have a version 236 in the ISO C standard; in this case CX markings are added as appropriate to show where the 237 ISO C standard has been extended. Any conflict between this volume of IEEE Std. 1003.1-200x 238 and the ISO C standard is unintentional. 239 This volume of IEEE Std. 1003.1-200x also allows, but does not require, mathematics functions to 240 support IEEE Std. 754-1985 and IEEE Std. 854-1987. 500 Technical Standard (2000) (Draft July 31, 2000) Introduction Portability 241 1.9 Portability 242 Some of the utilities in the Shell and Utilities volume of IEEE Std. 1003.1-200x and functions in 243 the System Interfaces volume of IEEE Std. 1003.1-200x describe functionality that might not be 244 fully portable to systems meeting the requirements for POSIX conformance (see the Base 245 Definitions volume of IEEE Std. 1003.1-200x, Chapter 2, Conformance). 246 Where optional, enhanced, or reduced functionality is specified, the text is shaded and a code in 247 the margin identifies the nature of the option, extension, or warning (see Section 1.9.1). For 248 maximum portability, an application should avoid such functionality. 249 1.9.1 Codes 250 Margin codes and their meanings are listed in the Base Definitions volume of 251 IEEE Std. 1003.1-200x, but are repeated here for convenience: 252 ADV Advisory Information 253 The functionality described is optional. The functionality described is also an extension to the 254 ISO C standard. 255 Where applicable, functions are marked with the ADV margin legend in the SYNOPSIS section. 256 Where additional semantics apply to a function, the material is identified by use of the ADV 257 margin legend. 258 AIO Asynchronous Input and Output 259 The functionality described is optional. The functionality described is also an extension to the 260 ISO C standard. 261 Where applicable, functions are marked with the AIO margin legend in the SYNOPSIS section. 262 Where additional semantics apply to a function, the material is identified by use of the AIO 263 margin legend. 264 BAR Barriers 265 The functionality described is optional. The functionality described is also an extension to the 266 ISO C standard. 267 Where applicable, functions are marked with the BAR margin legend in the SYNOPSIS section. 268 Where additional semantics apply to a function, the material is identified by use of the BAR 269 margin legend. 270 BE Batch Environment Services and Utilities 271 The functionality described is optional. 272 Where applicable, utilities are marked with the BE margin legend in the SYNOPSIS section. 273 Where additional semantics apply to a utility, the material is identified by use of the BE margin 274 legend. 275 CD C-Language Development Utilities 276 The functionality described is optional. 277 Where applicable, utilities are marked with the CD margin legend in the SYNOPSIS section. 278 Where additional semantics apply to a utility, the material is identified by use of the CD margin 279 legend. 280 CPT Process CPU-Time Clocks 281 The functionality described is optional. The functionality described is also an extension to the 282 ISO C standard. 283 Where applicable, functions are marked with the CPT margin legend in the SYNOPSIS section. 284 Where additional semantics apply to a function, the material is identified by use of the CPT System Interfaces, Issue 6 501 Portability Introduction 285 margin legend. 286 CS Clock Selection 287 The functionality described is optional. The functionality described is also an extension to the 288 ISO C standard. 289 Where applicable, functions are marked with the CS margin legend in the SYNOPSIS section. 290 Where additional semantics apply to a function, the material is identified by use of the CS 291 margin legend. 292 CX Extension to the ISO C standard 293 The functionality described is an extension to the ISO C standard. Application writers may 294 make use of an extension as it is supported on all IEEE Std. 1003.1-200x-conforming systems. 295 FD FORTRAN Development Utilities 296 The functionality described is optional. 297 Where applicable, utilities are marked with the FD margin legend in the SYNOPSIS section. 298 Where additional semantics apply to a utility, the material is identified by use of the FD margin 299 legend. 300 FR FORTRAN Runtime Utilities 301 The functionality described is optional. 302 Where applicable, utilities are marked with the FR margin legend in the SYNOPSIS section. 303 Where additional semantics apply to a utility, the material is identified by use of the FR margin 304 legend. 305 FSC File Synchronization 306 The functionality described is optional. The functionality described is also an extension to the 307 ISO C standard. 308 Where applicable, functions are marked with the FSC margin legend in the SYNOPSIS section. 309 Where additional semantics apply to a function, the material is identified by use of the FSC 310 margin legend. 311 IP6 IPV6 312 The functionality described is optional. The functionality described is also an extension to the 313 ISO C standard. 314 Where applicable, functions are marked with the IP6 margin legend in the SYNOPSIS section. 315 Where additional semantics apply to a function, the material is identified by use of the IP6 316 margin legend. 317 MAN Mandatory in the Next Draft 318 This is an interim draft code used to aid reviewers during the development of 319 IEEE Std. 1003.1-200x. It denotes a feature that was previously an option or extension that is 320 being brought into the mandatory base functionality. This margin code will be removed from the 321 final draft. 322 MF Memory Mapped Files 323 The functionality described is optional. The functionality described is also an extension to the 324 ISO C standard. 325 Where applicable, functions are marked with the MF margin legend in the SYNOPSIS section. 326 Where additional semantics apply to a function, the material is identified by use of the MF 327 margin legend. 328 ML Process Memory Locking 329 The functionality described is optional. The functionality described is also an extension to the 502 Technical Standard (2000) (Draft July 31, 2000) Introduction Portability 330 ISO C standard. 331 Where applicable, functions are marked with the ML margin legend in the SYNOPSIS section. 332 Where additional semantics apply to a function, the material is identified by use of the ML 333 margin legend. 334 MLR Range Memory Locking 335 The functionality described is optional. The functionality described is also an extension to the 336 ISO C standard. 337 Where applicable, functions are marked with the MLR margin legend in the SYNOPSIS section. 338 Where additional semantics apply to a function, the material is identified by use of the MLR 339 margin legend. 340 MON Monotonic Clock 341 The functionality described is optional. The functionality described is also an extension to the 342 ISO C standard. 343 Where applicable, functions are marked with the MON margin legend in the SYNOPSIS section. 344 Where additional semantics apply to a function, the material is identified by use of the MON 345 margin legend. 346 MPR Memory Protection 347 The functionality described is optional. The functionality described is also an extension to the 348 ISO C standard. 349 Where applicable, functions are marked with the MPR margin legend in the SYNOPSIS section. 350 Where additional semantics apply to a function, the material is identified by use of the MPR 351 margin legend. 352 MSG Message Passing 353 The functionality described is optional. The functionality described is also an extension to the 354 ISO C standard. 355 Where applicable, functions are marked with the MSG margin legend in the SYNOPSIS section. 356 Where additional semantics apply to a function, the material is identified by use of the MSG 357 margin legend. 358 OB Obsolescent 359 The functionality described may be withdrawn in a future version of this volume of 360 IEEE Std. 1003.1-200x. Strictly Conforming POSIX Applications and Strictly Conforming XSI 361 Applications shall not use obsolescent features. 362 OF Output Format Incompletely Specified 363 The functionality described is an XSI extension. The format of the output produced by the utility 364 is not fully specified. It is therefore not possible to post-process this output in a consistent 365 fashion. Typical problems include unknown length of strings and unspecified field delimiters. 366 OH Optional Header 367 In the SYNOPSIS section of some interfaces in the System Interfaces volume of 368 IEEE Std. 1003.1-200x an included header is marked as in the following example: 369 OH #include 370 #include 371 struct group *getgrnam(const char *name); 372 This indicates that the marked header is not required on XSI-conformant systems. System Interfaces, Issue 6 503 Portability Introduction 373 PIO Prioritized Input and Output 374 The functionality described is optional. The functionality described is also an extension to the 375 ISO C standard. 376 Where applicable, functions are marked with the PIO margin legend in the SYNOPSIS section. 377 Where additional semantics apply to a function, the material is identified by use of the PIO 378 margin legend. 379 PS Process Scheduling 380 The functionality described is optional. The functionality described is also an extension to the 381 ISO C standard. 382 Where applicable, functions are marked with the PS margin legend in the SYNOPSIS section. 383 Where additional semantics apply to a function, the material is identified by use of the PS 384 margin legend. 385 RTS Realtime Signals Extension 386 The functionality described is optional. The functionality described is also an extension to the 387 ISO C standard. 388 Where applicable, functions are marked with the RTS margin legend in the SYNOPSIS section. 389 Where additional semantics apply to a function, the material is identified by use of the RTS 390 margin legend. 391 SD Software Development Utilities 392 The functionality described is optional. 393 Where applicable, utilities are marked with the SD margin legend in the SYNOPSIS section. 394 Where additional semantics apply to a utility, the material is identified by use of the SD margin 395 legend. 396 SEM Semaphores 397 The functionality described is optional. The functionality described is also an extension to the 398 ISO C standard. 399 Where applicable, functions are marked with the SEM margin legend in the SYNOPSIS section. 400 Where additional semantics apply to a function, the material is identified by use of the SEM 401 margin legend. 402 SHM Shared Memory Objects 403 The functionality described is optional. The functionality described is also an extension to the 404 ISO C standard. 405 Where applicable, functions are marked with the SHM margin legend in the SYNOPSIS section. 406 Where additional semantics apply to a function, the material is identified by use of the SHM 407 margin legend. 408 SIO Synchronized Input and Output 409 The functionality described is optional. The functionality described is also an extension to the 410 ISO C standard. 411 Where applicable, functions are marked with the SIO margin legend in the SYNOPSIS section. 412 Where additional semantics apply to a function, the material is identified by use of the SIO 413 margin legend. 414 SPI Spin Locks 415 The functionality described is optional. The functionality described is also an extension to the 416 ISO C standard. 504 Technical Standard (2000) (Draft July 31, 2000) Introduction Portability 417 Where applicable, functions are marked with the SPI margin legend in the SYNOPSIS section. 418 Where additional semantics apply to a function, the material is identified by use of the SPI 419 margin legend. 420 SPN Spawn 421 The functionality described is optional. The functionality described is also an extension to the 422 ISO C standard. 423 Where applicable, functions are marked with the SPN margin legend in the SYNOPSIS section. 424 Where additional semantics apply to a function, the material is identified by use of the SPN 425 margin legend. 426 SS Process Sporadic Server 427 The functionality described is optional. The functionality described is also an extension to the 428 ISO C standard. 429 Where applicable, functions are marked with the SS margin legend in the SYNOPSIS section. 430 Where additional semantics apply to a function, the material is identified by use of the SS 431 margin legend. 432 TCT Thread CPU-Time Clocks 433 The functionality described is optional. The functionality described is also an extension to the 434 ISO C standard. 435 Where applicable, functions are marked with the TCT margin legend in the SYNOPSIS section. 436 Where additional semantics apply to a function, the material is identified by use of the TCT 437 margin legend. 438 THR Threads 439 The functionality described is optional. The functionality described is also an extension to the 440 ISO C standard. 441 Where applicable, functions are marked with the THR margin legend in the SYNOPSIS section. 442 Where additional semantics apply to a function, the material is identified by use of the THR 443 margin legend. 444 TMO Timeouts 445 The functionality described is optional. The functionality described is also an extension to the 446 ISO C standard. 447 Where applicable, functions are marked with the TMO margin legend in the SYNOPSIS section. 448 Where additional semantics apply to a function, the material is identified by use of the TMO 449 margin legend. 450 TMR Timers 451 The functionality described is optional. The functionality described is also an extension to the 452 ISO C standard. 453 Where applicable, functions are marked with the TMR margin legend in the SYNOPSIS section. 454 Where additional semantics apply to a function, the material is identified by use of the TMR 455 margin legend. 456 TPI Threads Priority Inheritance 457 The functionality described is optional. The functionality described is also an extension to the 458 ISO C standard. 459 Where applicable, functions are marked with the TPI margin legend in the SYNOPSIS section. 460 Where additional semantics apply to a function, the material is identified by use of the TPI 461 margin legend. System Interfaces, Issue 6 505 Portability Introduction 462 TPP Thread Priority Protection 463 The functionality described is optional. The functionality described is also an extension to the 464 ISO C standard. 465 Where applicable, functions are marked with the TPP margin legend in the SYNOPSIS section. 466 Where additional semantics apply to a function, the material is identified by use of the TPP 467 margin legend. 468 TPS Thread Execution Scheduling 469 The functionality described is optional. The functionality described is also an extension to the 470 ISO C standard. 471 Where applicable, functions are marked with the TPS margin legend for the SYNOPSIS section. 472 Where additional semantics apply to a function, the material is identified by use of the TPS 473 margin legend. 474 TRC Trace 475 The functionality described is optional. The functionality described is also an extension to the 476 ISO C standard. 477 Where applicable, functions are marked with the TRC margin legend in the SYNOPSIS section. 478 Where additional semantics apply to a function, the material is identified by use of the TRC 479 margin legend. 480 TEF Trace Event Filter 481 The functionality described is optional. The functionality described is also an extension to the 482 ISO C standard. 483 Where applicable, functions are marked with the TEF margin legend in the SYNOPSIS section. 484 Where additional semantics apply to a function, the material is identified by use of the TEF 485 margin legend. 486 TRL Trace Log 487 The functionality described is optional. The functionality described is also an extension to the 488 ISO C standard. 489 Where applicable, functions are marked with the TRL margin legend in the SYNOPSIS section. 490 Where additional semantics apply to a function, the material is identified by use of the TRL 491 margin legend. 492 TRI Trace Inherit 493 The functionality described is optional. The functionality described is also an extension to the 494 ISO C standard. 495 Where applicable, functions are marked with the TRI margin legend in the SYNOPSIS section. 496 Where additional semantics apply to a function, the material is identified by use of the TRI 497 margin legend. 498 TSA Thread Stack Address Attribute 499 The functionality described is optional. The functionality described is also an extension to the 500 ISO C standard. 501 Where applicable, functions are marked with the TPS margin legend for the SYNOPSIS section. 502 Where additional semantics apply to a function, the material is identified by use of the TSA 503 margin legend. 504 TSF Thread-Safe Functions 505 The functionality described is optional. The functionality described is also an extension to the 506 ISO C standard. 506 Technical Standard (2000) (Draft July 31, 2000) Introduction Portability 507 Where applicable, functions are marked with the TSF margin legend in the SYNOPSIS section. 508 Where additional semantics apply to a function, the material is identified by use of the TSF 509 margin legend. 510 TSH Thread Process-Shared Synchronization 511 The functionality described is optional. The functionality described is also an extension to the 512 ISO C standard. 513 Where applicable, functions are marked with the TSH margin legend in the SYNOPSIS section. 514 Where additional semantics apply to a function, the material is identified by use of the TSH 515 margin legend. 516 TSP Thread Sporadic Server 517 The functionality described is optional. The functionality described is also an extension to the 518 ISO C standard. 519 Where applicable, functions are marked with the TSP margin legend in the SYNOPSIS section. 520 Where additional semantics apply to a function, the material is identified by use of the TSP 521 margin legend. 522 TSS Thread Stack Address Size 523 The functionality described is optional. The functionality described is also an extension to the 524 ISO C standard. 525 Where applicable, functions are marked with the TSS margin legend in the SYNOPSIS section. 526 Where additional semantics apply to a function, the material is identified by use of the TSS 527 margin legend. 528 TYM Typed Memory Objects 529 The functionality described is optional. The functionality described is also an extension to the 530 ISO C standard. 531 Where applicable, functions are marked with the TYM margin legend in the SYNOPSIS section. 532 Where additional semantics apply to a function, the material is identified by use of the TYM 533 margin legend. 534 UN Possibly Unsupportable Feature 535 The functionality described is an XSI extension. It need not be possible to implement the 536 required functionality (as defined) on all conformant systems and the functionality need not be 537 present. This may, for example, be the case where the conformant system is hosted and the 538 underlying system provides the service in an alternative way. 539 UP User Portability Utilities 540 The functionality described is optional. 541 Where applicable, utilities are marked with the UP margin legend in the SYNOPSIS section. 542 Where additional semantics apply to a utility, the material is identified by use of the UP margin 543 legend. 544 XSI Extension 545 The functionality described is an XSI extension. Functionality marked XSI is also an extension to 546 the ISO C standard. Application writers may confidently make use of an extension on all 547 systems supporting the X/Open System Interfaces Extension. 548 If an entire SYNOPSIS section is shaded and marked with one XSI, all the functionality described 549 in that reference page is an extension. See the Base Definitions volume of IEEE Std. 1003.1-200x, 550 Section 3.441, XSI. System Interfaces, Issue 6 507 Portability Introduction 551 XSR XSI STREAMS 552 The functionality described is optional. The functionality described is also an extension to the 553 ISO C standard. 554 Where applicable, functions are marked with the XSR margin legend in the SYNOPSIS section. 555 Where additional semantics apply to a function, the material is identified by use of the XSR 556 margin legend. 508 Technical Standard (2000) (Draft July 31, 2000) Introduction Format of Entries 557 1.10 Format of Entries 558 The entries in Chapter 3 are based on a common format as follows. The only sections relating to 559 conformance are the SYNOPSIS, DESCRIPTION, RETURN VALUE, and ERRORS sections. 560 NAME 561 This section gives the name or names of the entry and briefly states its purpose. 562 SYNOPSIS 563 This section summarizes the use of the entry being described. If it is necessary to 564 include a header to use this function, the names of such headers are shown, for 565 example: 566 #include 567 DESCRIPTION 568 This section describes the functionality of the function or header. 569 RETURN VALUE 570 This section indicates the possible return values, if any. 571 If the implementation can detect errors, ``successful completion'' means that no error 572 has been detected during execution of the function. If the implementation does detect 573 an error, the error is indicated. 574 For functions where no errors are defined, ``successful completion'' means that if the 575 implementation checks for errors, no error has been detected. If the implementation can 576 detect errors, and an error is detected, the indicated return value is returned and errno 577 may be set. 578 ERRORS 579 This section gives the symbolic names of the values returned in errno if an error occurs. 580 ``No errors are defined'' means that values and usage of errno, if any, depend on the 581 implementation. 582 EXAMPLES 583 This section is non-normative. 584 This section gives examples of usage, where appropriate. In the event of conflict 585 between an example and a normative part of this volume of IEEE Std. 1003.1-200x, the 586 normative material is to be taken as correct. 587 APPLICATION USAGE 588 This section is non-normative. 589 This section gives warnings and advice to application writers about the entry. In the 590 event of conflict between warnings and advice and a normative part of this volume of 591 IEEE Std. 1003.1-200x, the normative material is to be taken as correct. 592 RATIONALE 593 This section is non-normative. 594 This section contains historical information concerning the contents of this volume of 595 IEEE Std. 1003.1-200x and why features were included or discarded by the standard 596 developers. 597 FUTURE DIRECTIONS 598 This section is non-normative. System Interfaces, Issue 6 509 Format of Entries Introduction 599 This section provides comments which should be used as a guide to current thinking; 600 there is not necessarily a commitment to adopt these future directions. 601 SEE ALSO 602 This section is non-normative. 603 This section gives references to related information. 604 CHANGE HISTORY 605 This section is non-normative. 606 This section shows the derivation of the entry and any significant changes that have 607 been made to it. 510 Technical Standard (2000) (Draft July 31, 2000) Chapter 2 General Information 608 609 This chapter covers information that is relevant to all the functions specified in Chapter 3 and 610 the Base Definitions volume of IEEE Std. 1003.1-200x, Chapter 13, Headers. 611 2.1 Use and Implementation of Functions 612 Each of the following statements shall apply unless explicitly stated otherwise in the detailed 613 descriptions that follow: 614 1. If an argument to a function has an invalid value (such as a value outside the domain of 615 the function, or a pointer outside the address space of the program, or a null pointer), the 616 behavior is undefined. 617 2. Any function declared in a header may also be implemented as a macro defined in the 618 header, so a library function should not be declared explicitly if its header is included. Any 619 macro definition of a function can be suppressed locally by enclosing the name of the 620 function in parentheses, because the name is then not followed by the left parenthesis that 621 indicates expansion of a macro function name. For the same syntactic reason, it is 622 permitted to take the address of a library function even if it is also defined as a macro. The 623 use of the C-language #undef construct to remove any such macro definition shall also 624 ensure that an actual function is referred to. 625 3. Any invocation of a library function that is implemented as a macro shall expand to code 626 that evaluates each of its arguments exactly once, fully protected by parentheses where 627 necessary, so it is generally safe to use arbitrary expressions as arguments. Likewise, those 628 function-like macros described in the following sections may be invoked in an expression 629 anywhere a function with a compatible return type could be called. 630 4. Provided that a library function can be declared without reference to any type defined in a 631 header, it is also permissible to declare the function, either explicitly or implicitly, and use 632 it without including its associated header. 633 5. If a function that accepts a variable number of arguments is not declared (explicitly or by 634 including its associated header), the behavior is undefined. System Interfaces, Issue 6 511 The Compilation Environment General Information 635 2.2 The Compilation Environment 636 2.2.1 POSIX.1 Symbols 637 Certain symbols in this volume of IEEE Std. 1003.1-200x are defined in headers (see the Base 638 Definitions volume of IEEE Std. 1003.1-200x, Chapter 13, Headers). Some of those headers could 639 also define other symbols than those defined by this volume of IEEE Std. 1003.1-200x, potentially 640 conflicting with symbols used by the application. Also, this volume of IEEE Std. 1003.1-200x 641 defines symbols that are not permitted by other standards to appear in those headers without 642 some control on the visibility of those symbols. 643 Symbols called feature test macros are used to control the visibility of symbols that might be 644 included in a header. Implementations, future versions of this volume of IEEE Std. 1003.1-200x, 645 and other standards may define additional feature test macros. 646 In the compilation of an application that #defines a feature test macro specified by 647 IEEE Std. 1003.1-200x, no header defined by IEEE Std. 1003.1-200x shall be included prior to the 648 definition of the feature test macro. This restriction also applies to any implementation- 649 provided header in which these feature test macros are used. If the definition of the macro does 650 not precede the #include, the result is undefined. 651 Feature test macros shall begin with the underscore character ('_'). 652 2.2.1.1 The _POSIX_C_SOURCE Feature Test Macro 653 A POSIX-conforming application should ensure that the feature test macro _POSIX_C_SOURCE 654 is defined before inclusion of any header. 655 When an application includes a header described by this volume of IEEE Std. 1003.1-200x, and 656 when this feature test macro is defined to have at least the value 200xMML: 657 1. All symbols required by this volume of IEEE Std. 1003.1-200x to appear when the header is 658 included shall be made visible. 659 2. Symbols that are explicitly permitted, but not required, by this volume of 660 IEEE Std. 1003.1-200x to appear in that header (including those in reserved name spaces) 661 may be made visible. 662 3. Additional symbols not required or explicitly permitted by this volume of 663 IEEE Std. 1003.1-200x to be in that header shall not be made visible, except when enabled 664 by another feature test macro or by having defined _POSIX_C_SOURCE with a value 665 larger than 200xxxL. 666 Identifiers in this volume of IEEE Std. 1003.1-200x may only be undefined using the #undef 667 directive as described in Section 2.1 (on page 511) or Section 2.2.2 (on page 513). These #undef 668 directives shall follow all #include directives of any header in this volume of 669 IEEE Std. 1003.1-200x. 670 2.2.1.2 The _XOPEN_SOURCE Feature Test Macro 671 XSI An XSI-conforming application should ensure that the feature test macro _XOPEN_SOURCE is 672 defined with the value 600 before inclusion of any header. This is needed to enable the 673 functionality described in Section 2.2.1.1 and in addition to enable the X/Open System Interfaces 674 Extension. 675 Since this volume of IEEE Std. 1003.1-200x is aligned with the ISO C standard, and since all 676 functionality enabled by _POSIX_C_SOURCE set greater than zero and less than or equal to 677 200xxxL should be enabled by _XOPEN_SOURCE set equal to 600, there should be no need to 512 Technical Standard (2000) (Draft July 31, 2000) General Information The Compilation Environment 678 define either _POSIX_SOURCE or _POSIX_C_SOURCE if _XOPEN_SOURCE is so defined. 679 Therefore, if _XOPEN_SOURCE is set equal to 600 and _POSIX_SOURCE is defined, or 680 _POSIX_C_SOURCE is set greater than zero and less than or equal to 200xxxL, the behavior is 681 the same as if only _XOPEN_SOURCE is defined and set equal to 600. However, should 682 _POSIX_C_SOURCE be set to a value greater than 200xxxL, the behavior is undefined. 683 2.2.2 The Name Space 684 All identifiers in this volume of IEEE Std. 1003.1-200x, except environ, are defined in at least one 685 of the headers, as shown in the Base Definitions volume of IEEE Std. 1003.1-200x, Chapter 13, 686 XSI Headers. When _XOPEN_SOURCE or _POSIX_C_SOURCE is defined, each header defines or 687 declares some identifiers, potentially conflicting with identifiers used by the application. The set 688 of identifiers visible to the application consists of precisely those identifiers from the header 689 pages of the included headers, as well as additional identifiers reserved for the implementation. 690 In addition, some headers may make visible identifiers from other headers as indicated on the 691 relevant header pages. 692 Implementations may also add members to a structure or union without controlling the 693 visibility of those members with a feature test macro, as long as a user-defined macro with the 694 same name cannot interfere with the correct interpretation of the program. The identifiers 695 reserved for use by the implementation are described below: 696 1. Each identifier with external linkage described in the header section is reserved for use as 697 an identifier with external linkage if the header is included. 698 2. Each macro name described in the header section is reserved for any use if the header is 699 included. 700 3. Each identifier with file scope described in the header section is reserved for use as an 701 identifier with file scope in the same name space if the header is included. 702 The prefixes posix_, POSIX_, and _POSIX_ are reserved for use by IEEE Std. 1003.1-200x and 703 other POSIX standards. Implementations may add symbols to the headers shown in the 704 following table, provided the identifiers for those symbols begin with the corresponding 705 reserved prefixes in the following table, and do not use the reserved prefixes posix_, POSIX_, or 706 _POSIX_. System Interfaces, Issue 6 513 The Compilation Environment General Information 707 ______________________________________________________________________________________ 708 Complete 709 _ Header Prefix Suffix Name _____________________________________________________________________________________ 710 AIO aio_, lio_, AIO_, LIO_ 711 in_, inet_ 712 to[a-z], is[a-z] 713 d_ 714 E[0-9], E[A-Z] 715 l_ 716 gl_ 717 gr_ 718 int[0-9a-z_]_t, uint[0-9a-z_]_t 719 _MAX, _MIN 720 LC_[A-Z] 721 MSG mq_, MQ_ 722 XSI dbm_ 723 h_, n_, p_, s_ 724 if_ 725 in_, ip_, s_, sin_ 726 XSI pd_, ph_, ps_ 727 pthread_, PTHREAD_ 728 pw_ 729 re_, rm_ 730 PS sched_, SCHED_ 731 SEM sem_, SEM_ 732 sa_, uc_, SIG[A-Z], SIG_[A-Z] 733 XSI ss_, sv_ 734 RTS si_, SI_, sigev_, SIGEV_, sival_ 735 XSI bi_, ic_, l_, sl_, str_ 736 int[0-9a-z_]_t, uint[0-9a-z_]_t 737 str[a-z] 738 str[a-z], mem[a-z], wcs[a-z] 739 XSI ipc_ key, pad, seq 740 MF shm_, MAP_, MCL_, MS_, PROT_ 741 XSI msg msg 742 XSI rlim_, ru_ 743 XSI sem sem 744 XSI shm 745 _ss, sa_, if_, ifc_, ifru_, infu_, ifra_, 746 msg_, cmsg_, l_ 747 st_ 748 XSI f_ 749 fds_, it_, tv_, FD_ 750 tms_ 751 XSI iov_ 752 sun_ 753 uts_ 754 XSI si_, W[A-Z], P_ 755 _ c_ _____________________________________________________________________________________ 514 Technical Standard (2000) (Draft July 31, 2000) General Information The Compilation Environment 756 ______________________________________________________________________________________ 757 Complete 758 _ Header Prefix Suffix Name _____________________________________________________________________________________ 759 tm_ 760 TMR clock_, timer_, it_, tv_, 761 TMR CLOCK_, TIMER_ 762 XSI uc_, ss_ 763 XSI UL_ 764 utim_ 765 XSI ut_ _LVL, _TIME, 766 _PROCESS 767 wcs[a-z] 768 is[a-z], to[a-z] 769 we_ 770 _ ANY header POSIX_, _POSIX_, posix_ _t _____________________________________________________________________________________ 771 Note: The notation [A-Z] indicates any uppercase letter in the portable character set. The 772 notation [a-z] indicates any lowercase letter in the portable character set. Commas 773 and spaces in the lists of prefixes and complete names in the above table are not part 774 of any prefix or complete name. 775 If any header in the following table is included, macros with the prefixes shown may be defined. | 776 After the last inclusion of a given header, an application may use identifiers with the 777 corresponding prefixes for its own purpose, provided their use is preceded by an #undef of the 778 corresponding macro. System Interfaces, Issue 6 515 The Compilation Environment General Information 779 _____________________________________________________________________________________ 780 _ Header Prefix ____________________________________________________________________________________ 781 XSI RTLD_ 782 F_, O_, S_ 783 XSI MM_ 784 FNM_ 785 XSI FTW 786 GLOB_ 787 PRI[a-z], SCN[a-z] 788 XSI DBM_ 789 IF_ 790 IMPLINK_, IN_, INADDR_, IP_, IPPORT_, IPPROTO_, SOCK_ 791 TCP_ 792 XSI NL_ 793 XSI POLL 794 REG_ 795 SA_, SIG_[0-9a-z_], 796 XSI BUS_, CLD_, FPE_, ILL_, POLL_, SEGV_, SI_, SS_, SV_, TRAP_ 797 stdint.h INT[0-9A-Z_]_MIN, INT[0-9A-Z_]_MAX, INT[0-9A-Z_]_C 798 UINT[0-9A-Z_]_MIN, UINT[0-9A-Z_]_MAX, UINT[0-9A-Z_]_C 799 XSI FLUSH[A-Z], I_, M_, MUXID_R[A-Z], S_, SND[A-Z], STR 800 XSI LOG_ 801 XSI IPC_ 802 XSI PROT_, MAP_, MS_ 803 XSI MSG[A-Z] 804 XSI PRIO_, RLIM_, RLIMIT_, RUSAGE_ 805 XSI SEM_ 806 XSI SHM[A-Z], SHM_[A-Z] 807 XSI AF_, CMSG_, MSG_, PF_, SCM_, SHUT_, SO 808 S_ 809 XSI ST_ 810 XSI FD_, ITIMER_ 811 XSI IOV_ 812 XSI BUS_, CLD_, FPE_, ILL_, POLL_, SEGV_, SI_, TRAP_ 813 V, I, O, TC, B[0-9] (See below.) 814 _ WRDE_ ____________________________________________________________________________________ 815 Note: The notation [0-9] indicates any digit. The notation [A-Z] indicates any uppercase 816 letter in the portable character set. The notation [0-9a-z_] indicates any digit, any 817 lowercase letter in the portable character set, or underscore. 818 The following reserved names are used as exact matches for : | 819 XSI CBAUD EXTB VDSUSP | 820 DEFECHO FLUSHO VLNEXT | 821 ECHOCTL LOBLK VREPRINT | 822 ECHOKE PENDIN VSTATUS | 823 ECHOPRT SWTCH VWERASE | 824 EXTA VDISCARD | 516 Technical Standard (2000) (Draft July 31, 2000) General Information The Compilation Environment 825 The following identifiers are reserved regardless of the inclusion of headers: | 826 1. All identifiers that begin with an underscore and either an uppercase letter or another 827 underscore are always reserved for any use by the implementation. 828 2. All identifiers that begin with an underscore are always reserved for use as identifiers with 829 file scope in both the ordinary identifier and tag name spaces. 830 3. All identifiers in the table below are reserved for use as identifiers with external linkage. 831 Some of these identifiers do not appear in this volume of IEEE Std. 1003.1-200x, but are 832 reserved for future use by the ISO C standard. | 833 _Exit | cbrtf | exit | fsetpos | mbrtowc | sinhl |||||| || 834 abort | cbrtl | exp | ftell | mbsinit | sinl ||||| || 835 abs | ccos | exp2 | fwide | mbsrtowcs | sprintf ||||| || 836 acos | ccosf | exp2f | fwprintf | mbstowcs | sqrt ||||| || 837 acosf | ccosh | exp2l | fwrite | mbtowc | sqrtf ||||| || 838 acosh | ccoshf | expf | fwscanf | mem[a-z]* | sqrtl ||||| || 839 acoshf | ccoshl | expl | getc | mktime | srand ||||| || 840 acoshl | ccosl | expm1 | getchar | modf | sscanf ||||| || 841 acosl | ceil | expm1f | getenv | modff | str[a-z]* ||||| || 842 acosl | ceilf | expm1l | gets | modfl | strtof ||||| || 843 asctime | ceilf | fabs | getwc | nan | strtoimax ||||| || 844 asin | ceill | fabsf | getwchar | nanf | strtold ||||| || 845 asinf | ceill | fabsl | gmtime | nanl | strtoll ||||| || 846 asinh | cexp | fclose | hypotf | nearbyint | strtoull ||||| || 847 asinhf | cexpf | fdim | hypotl | nearbyintf | strtoumax ||||| || 848 asinhl | cexpl | fdimf | ilogb | nearbyintl | swprintf ||||| || 849 asinl | cimag | fdiml | ilogbf | nextafterf | swscanf ||||| || 850 asinl | cimagf f| eclearexcept | ilogbl | nextafterl | system ||||| || 851 atan | cimagl | fegetenv | imaxabs | nexttoward | tan ||||| || 852 atan2 | clearerr | fegetexceptflag | imaxdiv | nexttowardf | tanf ||||| || 853 atan2f | clock | fegetround | is[a-z]* | nexttowardl | tanh ||||| || 854 atan2l | clog f| eholdexcept | isblank | perror | tanhf ||||| || 855 atanf | clogf | feof | iswblank | pow | tanhl ||||| || 856 atanf | clogl f| eraiseexcept | labs | powf | tanl ||||| || 857 atanh | conj | ferror | ldexp | powl | tgamma ||||| || 858 atanh | conjf | fesetenv | ldexpf | printf | tgammaf ||||| || 859 atanhf | conjl | fesetexceptflag | ldexpl | putc | tgammal ||||| || 860 atanhl | copysign | fesetround | ldiv | putchar | time ||||| || 861 atanl | copysignf | fetestexcept | ldiv | puts | tmpfile ||||| || 862 atanl | copysignl | feupdateenv | lgammaf | putwc | tmpnam ||||| || 863 atexit | cos | fflush | lgammal | putwchar | to[a-z]* ||||| || 864 atof | cosf | fgetc | llabs | qsort | trunc ||||| || 865 atoi | cosh | fgetpos | llrint | raise | truncf ||||| || 866 atol | coshf | fgets | llrintf | rand | truncl ||||| || 867 atoll | coshl | fgetwc | llrintl | realloc | ungetc ||||| || 868 bsearch | cosl | fgetws | llround | remainderf | ungetwc ||||| || 869 cabs | cpow | floor | llroundf | remainderl | va_end ||||| || 870 cabsf | cpowf | floorf | llroundl | remove | vfprintf ||||| || 871 cabsl | cpowl | floorl | localeconv | remquo | vfscanf ||||| || 872 cacos | cproj | fma | localtime | remquof | vfwprintf ||||| || System Interfaces, Issue 6 517 The Compilation Environment General Information 873 cacosf cprojf | fmaf | log | remquol | vfwscanf | ||| ||| |||| ||||| |||||| ||||||| 874 cacosh cprojl | fmal | log10 | rename | vprintf | ||| ||| |||| ||||| |||||| ||||||| 875 cacoshf creal | fmax | log10f | rewind | vscanf | ||| ||| |||| ||||| |||||| ||||||| 876 cacoshl crealf | fmaxf | log10l | rint | vsprintf | ||| ||| |||| ||||| |||||| ||||||| 877 cacosl creall | fmaxl | log1p | rintf | vsscanf | ||| ||| |||| ||||| |||||| ||||||| 878 calloc csin | fmin | log1pf | rintl | vswprintf | ||| ||| |||| ||||| |||||| ||||||| 879 carg csinf | fminf | log1pl | round | vswscanf | ||| ||| |||| ||||| |||||| ||||||| 880 cargf csinh | fminl | log2 | roundf | vwprintf | ||| ||| |||| ||||| |||||| ||||||| 881 cargl csinhf | fmod | log2f | roundl | vwscanf | ||| ||| |||| ||||| |||||| ||||||| 882 casin csinhl | fmodf | log2l | scalbln | wcrtomb | ||| ||| |||| ||||| |||||| ||||||| 883 casinf csinl | fmodl | logb | scalblnf | wcs[a-z]* | ||| ||| |||| ||||| |||||| ||||||| 884 casinh csqrt | fopen | logbf | scalblnl | wcstof | ||| ||| |||| ||||| |||||| ||||||| 885 casinhf csqrtf | fprintf | logbl | scalbn | wcstoimax | ||| ||| |||| ||||| |||||| ||||||| 886 casinhl csqrtl | fputc | logf | scalbnf | wcstold | ||| ||| |||| ||||| |||||| ||||||| 887 casinl ctan | fputs | logl | scalbnl | wcstoll | ||| ||| |||| ||||| |||||| ||||||| 888 catan ctanf | fputwc | longjmp | scanf | wcstoull | ||| ||| |||| ||||| |||||| ||||||| 889 catanf ctanl | fputws | lrint | setbuf | wcstoumax | ||| ||| |||| ||||| |||||| ||||||| 890 catanh ctime | fread | lrintf | setjmp | wctob | ||| ||| |||| ||||| |||||| ||||||| 891 catanh difftime | free | lrintl | setlocale | wctomb | ||| ||| |||| ||||| |||||| ||||||| 892 catanhf div | freopen | lround | setvbuf | wctrans | ||| ||| |||| ||||| |||||| ||||||| 893 catanhf erfcf | frexp | lroundf | signal | wctype | ||| ||| |||| ||||| |||||| ||||||| 894 catanhl erfcl | frexpf | lroundl | sin | wcwidth | ||| ||| |||| ||||| |||||| ||||||| 895 catanhl erff | frexpl | malloc | sinf | wmem[a-z]* | ||| ||| |||| ||||| |||||| ||||||| 896 catanl erfl | fscanf | mblen | sinh | wprintf | ||| ||| |||| ||||| |||||| ||||||| 897 cbrt errno | fseek | mbrlen | sinhf | wscanf | ||| ||| |||| ||||| |||||| ||||||| 898 Note: The notation [a-z] indicates any lowercase letter in the portable character set. | 899 The notation '*' indicates any combination of digits, letters in the portable | 900 character set, and underscore. | 518 Technical Standard (2000) (Draft July 31, 2000) General Information The Compilation Environment 901 Notes to Reviewers | 902 This section with side shading will not appear in the final copy. - Ed. | 903 The following table should be made complete by including everything not in the previous | 904 table. | 905 4. The following identifiers are also reserved for use as identifiers with external linkage: | 906 Table 2-1 XSI Identifiers | 907 XSI a64l | fattach | getpriority | mknod | regex | sigrelse |||||| || | 908 basename | fchdir | getpwent | mkstemp | remainder | sigset ||||| || 909 bcmp | fchmod | getrlimit | mktemp | remque | sigstack ||||| || 910 bcopy | fchown | getrusage | mmap | rindex | srandom ||||| || 911 brk | fcvt | getsid | mprotect | sbrk | statvfs ||||| || 912 bsd_signal | fdetach | getsubopt | mrand48 | scalb | strcasecmp ||||| || 913 bzero ffs| ge| ttimeofday | msync | select | strdup ||||| || 914 cbrt | fmtmsg | getutxent | munmap | setcontext | strncasecmp ||||| || 915 closelog | fstatvfs | getutxid | nextafter | setgrent | swapcontext ||||| || 916 dbm_clearerr | ftime | getutxline | nftw | setitimer | symlink ||||| || 917 dbm_close | ftok | getwd | nice | _setjmp | sync ||||| || 918 dbm_delete | ftruncate | grantpt | openlog | setlogmask | syslog ||||| || 919 dbm_error | gcvt | index | poll | setpgrp | tcgetsid ||||| || 920 dbm_fetch | getcontext | initstate | ptsname | setpriority | truncate ||||| || 921 dbm_firstkey | getdate | insque | putmsg | setpwent | ttyslot ||||| || 922 dbm_nextkey ge| tdtablesize | ioctl | putpmsg | setreuid | ualarm ||||| || 923 dbm_open | getgrent | isastream | pututxline | setrlimit | unlockpt ||||| || 924 dbm_store | getgrgid | killpg | random | setstate | usleep ||||| || 925 dirname | gethostid | l64a | readlink | setutxent | utimes ||||| || 926 ecvt | getitimer | lchown | readv | sigaltstack | valloc ||||| || 927 endgrent | getmsg | lockf | realpath | sighold | vfork ||||| || 928 endpwent | getpagesize | _longjmp | re_comp | sigignore | wait3 ||||| || 929 endservent | getpgid | lstat | re_exec | siginterrupt | waitid ||||| || 930 endutxent | getpmsg | makecontext | regcmp | sigpause | writev ||||| || 931 Table 2-2 Sockets Identifiers | 932 accept if_fr | eenameindex | recvfrom | shutdown | ||||| 933 bind if_i | ndextoname | recvmsg | socket | |||| 934 connect | if_nameindex send| | socketpair | |||| 935 getpeername if_n | ametoindex | sendmsg | ||| 936 getsockname | listen | sendto | ||| 937 getsockopt recv | | setsockopt | ||| System Interfaces, Issue 6 519 The Compilation Environment General Information 938 Table 2-3 IP Address Resolution Identifiers | 939 endhostent get| ipnodebyaddr | getservbyname | inet_netof | ||||| 940 endnetent get| ipnodebyname | getservbyport | inet_network | |||| 941 endprotoent | getnameinfo | getservent | inet_ntoa | |||| 942 endservent | getnetbyaddr | h_errno | ntohl | |||| 943 getaddrinfo | getnetbyname | htonl | ntohs | |||| 944 gethostbyaddr | getnetent | htons | sethostent | |||| 945 gethostbyname ge | tprotobyname | inet_addr | setnetent | |||| 946 gethostent ge | tprotobynumber | inet_lnaof | setprotoent | |||| 947 gethostname | getprotoent | inet_makeaddr | setservent | |||| 948 All the identifiers defined in this volume of IEEE Std. 1003.1-200x that have external linkage are | 949 always reserved for use as identifiers with external linkage. | 950 No other identifiers are reserved. | 951 Applications shall not declare or define identifiers with the same name as an identifier reserved | 952 in the same context. Since macro names are replaced whenever found, independent of scope and | 953 name space, macro names matching any of the reserved identifier names shall not be defined by | 954 an application if any associated header is included. | 955 Except that the effect of each inclusion of depends on the definition of NDEBUG, | 956 headers may be included in any order, and each may be included more than once in a given 957 scope, with no difference in effect from that of being included only once. | 958 If used, the application shall ensure that a header is included outside of any external declaration 959 or definition, and it shall be first included before the first reference to any type or macro it 960 defines, or to any function or object it declares. However, if an identifier is declared or defined in 961 more than one header, the second and subsequent associated headers may be included after the 962 initial reference to the identifier. Prior to the inclusion of a header, the application shall not 963 define any macros with names lexically identical to symbols defined by that header. 520 Technical Standard (2000) (Draft July 31, 2000) General Information Error Numbers 964 2.3 Error Numbers 965 Most functions can provide an error number. The means by which each function provides its 966 error numbers is specified in its description. 967 Some functions provide the error number in a variable accessed through the symbol errno. The 968 symbol errno, defined by including the header, is a macro that expands to a | 969 modifiable lvalue of type int. | 970 The value of errno should only be examined when it is indicated to be valid by a function's return 971 value. No function in this volume of IEEE Std. 1003.1-200x shall set errno to zero. For each thread | 972 of a process, the value of errno shall not be affected by function calls or assignments to errno by | 973 other threads. 974 Some functions return an error number directly as the function value. These functions return a 975 value of zero to indicate success. 976 If more than one error occurs in processing a function call, any one of the possible errors may be 977 returned, as the order of detection is undefined. 978 Implementations may support additional errors not included in this list, may generate errors 979 included in this list under circumstances other than those described here, or may contain 980 extensions or limitations that shall prevent some errors from occurring. The ERRORS section on 981 each page specifies whether an error shall be returned, or whether it may be returned. 982 Implementations shall not generate a different error number from the ones described here for 983 error conditions described in this volume of IEEE Std. 1003.1-200x, but may generate additional 984 errors unless explicitly disallowed for a particular function. 985 Each implementation shall document, in the conformance document, situations in which each of 986 the optional conditions defined in IEEE Std. 1003.1-200x are detected. The conformance 987 document may also contain statements that one or more of the optional error conditions are not 988 detected. | 989 For functions under the Threads option for which [EINTR] is not listed as a possible error | 990 condition in this volume of IEEE Std. 1003.1-200x, an implementation shall not return an error 991 code of [EINTR]. 992 The following symbolic names identify the possible error numbers, in the context of the 993 functions specifically defined in this volume of IEEE Std. 1003.1-200x; these general descriptions 994 are more precisely defined in the ERRORS sections of the functions that return them. Only these 995 symbolic names should be used in programs, since the actual value of the error number is | 996 unspecified. All values listed in this section shall be unique integer constant expressions with | 997 type int suitable for use in #if preprocessing directives, except as noted below. The values for all | 998 these names shall be found in the header defined in the Base Definitions volume of | 999 IEEE Std. 1003.1-200x. The actual values are unspecified by this volume of IEEE Std. 1003.1-200x. | 1000 [E2BIG] 1001 Argument list too long. The sum of the number of bytes used by the new process image's 1002 argument list and environment list is greater than the system-imposed limit of {ARG_MAX} 1003 bytes. 1004 or: 1005 Lack of space in an output buffer. 1006 or: 1007 Argument is greater than the system-imposed maximum. System Interfaces, Issue 6 521 Error Numbers General Information 1008 [EACCES] 1009 Permission denied. An attempt was made to access a file in a way forbidden by its file 1010 access permissions. | 1011 [EADDRINUSE] | 1012 Address in use. The specified address is in use. | 1013 [EADDRNOTAVAIL] | 1014 Address not available. The specified address is not available from the local system. | 1015 [EAFNOSUPPORT] | 1016 Address family not supported. The implementation does not support the specified address 1017 family, or the specified address is not a valid address for the address family of the specified 1018 socket. | 1019 [EAGAIN] 1020 Resource temporarily unavailable. This is a temporary condition and later calls to the same 1021 routine may complete normally. | 1022 [EALREADY] | 1023 Connection already in progress. A connection request is already in progress for the specified 1024 socket. | 1025 [EBADF] 1026 Bad file descriptor. A file descriptor argument is out of range, refers to no open file, or a 1027 read (write) request is made to a file that is only open for writing (reading). 1028 [EBADMSG] 1029 XSR Bad message. During a read( ), getmsg( ), or ioctl( ) I_RECVFD request to a STREAMS device, | 1030 a message arrived at the head of the STREAM that is inappropriate for the function 1031 receiving the message. 1032 read( ) Message waiting to be read on a STREAM is not a data message. 1033 getmsg( ) A file descriptor was received instead of a control message. 1034 ioctl( ) Control or data information was received instead of a file descriptor when 1035 I_RECVFD was specified. 1036 or: 1037 Bad Message. The implementation has detected a corrupted message. 1038 [EBUSY] 1039 Resource busy. An attempt was made to make use of a system resource that is not currently 1040 available, as it is being used by another process in a manner that would have conflicted with 1041 the request being made by this process. 1042 [ECANCELED] 1043 Operation canceled. The associated asynchronous operation was canceled before 1044 completion. 1045 [ECHILD] 1046 No child process. A wait( ) or waitpid( ) function was executed by a process that had no 1047 existing or unwaited-for child process. | 1048 [ECONNABORTED] | 1049 Connection aborted. The connection has been aborted. | 1050 [ECONNREFUSED] | 1051 Connection refused. An attempt to connect to a socket was refused because there was no 522 Technical Standard (2000) (Draft July 31, 2000) General Information Error Numbers 1052 process listening or because the queue of connection requests was full and the underlying 1053 protocol does not support retransmissions. | 1054 [ECONNRESET] | 1055 Connection reset. The connection was forcibly closed by the peer. | 1056 [EDEADLK] 1057 Resource deadlock would occur. An attempt was made to lock a system resource that 1058 would have resulted in a deadlock situation. | 1059 [EDESTADDRREQ] | 1060 Destination address required. No bind address was established. | 1061 [EDOM] 1062 Domain error. An input argument is outside the defined domain of the mathematical 1063 function (defined in the ISO C standard). | 1064 [EDQUOT] | 1065 Reserved. | 1066 [EEXIST] 1067 File exists. An existing file was mentioned in an inappropriate context; for example, as a 1068 new link name in the link( ) function. 1069 [EFAULT] 1070 Bad address. The system detected an invalid address in attempting to use an argument of a 1071 call. The reliable detection of this error cannot be guaranteed, and when not detected may 1072 result in the generation of a signal, indicating an address violation, which is sent to the 1073 process. | 1074 [EFBIG] | 1075 File too large. The size of a file would exceed the maximum file size of an implementation or 1076 offset maximum established in the corresponding file description. | 1077 [EHOSTUNREACH] | 1078 Host is unreachable. The destination host cannot be reached (probably because the host is 1079 down or a remote router cannot reach it). | 1080 [EIDRM] | 1081 Identifier removed. Returned during XSI interprocess communication if an identifier has 1082 been removed from the system. | 1083 [EILSEQ] | 1084 Illegal byte sequence. A wide-character code has been detected that does not correspond to | 1085 a valid character, or a byte sequence does not form a valid wide-character code (defined in | 1086 the ISO C standard). | 1087 [EINPROGRESS] | 1088 Operation in progress. This code is used to indicate that an asynchronous operation has not 1089 yet completed. 1090 or: 1091 O_NONBLOCK is set for the socket file descriptor and the connection cannot be 1092 immediately established. | 1093 [EINTR] | 1094 Interrupted function call. An asynchronous signal was caught by the process during the 1095 execution of an interruptible function. If the signal handler performs a normal return, the 1096 interrupted function call may return this condition (see the Base Definitions volume of | System Interfaces, Issue 6 523 Error Numbers General Information 1097 IEEE Std. 1003.1-200x, ). | 1098 [EINVAL] | 1099 Invalid argument. Some invalid argument was supplied; for example, specifying an 1100 undefined signal in a signal( ) function or a kill( ) function. | 1101 [EIO] 1102 Input/output error. Some physical input or output error has occurred. This error may be 1103 reported on a subsequent operation on the same file descriptor. Any other error-causing 1104 operation on the same file descriptor may cause the [EIO] error indication to be lost. | 1105 [EISCONN] | 1106 Socket is connected. The specified socket is already connected. | 1107 [EISDIR] 1108 Is a directory. An attempt was made to open a directory with write mode specified. | 1109 [ELOOP] | 1110 Symbolic link loop. A loop exists in symbolic links encountered during path name 1111 resolution. This error may also be returned if more than {SYMLOOP_MAX} symbolic links 1112 are encountered during path name resolution. | 1113 [EMFILE] 1114 Too many open files. An attempt was made to open more than the maximum number of 1115 {OPEN_MAX} file descriptors allowed in this process. 1116 [EMLINK] 1117 Too many links. An attempt was made to have the link count of a single file exceed 1118 {LINK_MAX}. | 1119 [EMSGSIZE] | 1120 Message too large. A message sent on a transport provider was larger than an internal 1121 message buffer or some other network limit. | 1122 or: | 1123 Inappropriate message buffer length. | 1124 [EMULTIHOP] | 1125 Reserved. | 1126 [ENAMETOOLONG] 1127 File name too long. The length of a path name exceeds {PATH_MAX}, or a path name 1128 component is longer than {NAME_MAX}. This error may also occur when path name | 1129 substitution, as a result of encountering a symbolic link during path name resolution, 1130 results in a path name string the size of which exceeds {PATH_MAX}. | 1131 [ENETDOWN] | 1132 Network is down. The local network interface used to reach the destination is down. | 1133 [ENETRESET] 1134 The connection was aborted by the network. | 1135 [ENETUNREACH] | 1136 Network unreachable. No route to the network is present. | 1137 [ENFILE] 1138 Too many files open in system. Too many files are currently open in the system. The system 1139 has reached its predefined limit for simultaneously open files and temporarily cannot accept 1140 requests to open another one. | 524 Technical Standard (2000) (Draft July 31, 2000) General Information Error Numbers 1141 [ENOBUFS] | 1142 No buffer space available. Insufficient buffer resources were available in the system to 1143 perform the socket operation. | 1144 XSR [ENODATA] | 1145 No message available. No message is available on the STREAM head read queue. 1146 [ENODEV] 1147 No such device. An attempt was made to apply an inappropriate function to a device; for 1148 example, trying to read a write-only device such as a printer. 1149 [ENOENT] 1150 No such file or directory. A component of a specified path name does not exist, or the path 1151 name is an empty string. 1152 [ENOEXEC] 1153 Executable file format error. A request is made to execute a file that, although it has the 1154 appropriate permissions, is not in the format required by the implementation for executable 1155 files. 1156 [ENOLCK] 1157 No locks available. A system-imposed limit on the number of simultaneous file and record 1158 locks has been reached and no more are currently available. | 1159 [ENOLINK] | 1160 Reserved. | 1161 [ENOMEM] 1162 Not enough space. The new process image requires more memory than is allowed by the 1163 hardware or system-imposed memory management constraints. | 1164 [ENOMSG] | 1165 No message of the desired type. The message queue does not contain a message of the 1166 required type during XSI interprocess communication. | 1167 [ENOPROTOOPT] | 1168 Protocol not available. The protocol option specified to setsockopt( ) is not supported by the 1169 implementation. | 1170 [ENOSPC] 1171 No space left on a device. During the write( ) function on a regular file or when extending a 1172 directory, there is no free space left on the device. 1173 XSR [ENOSR] | 1174 No STREAM resources. Insufficient STREAMS memory resources are available to perform a 1175 STREAMS-related function. This is a temporary condition; it may be recovered from if other 1176 processes release resources. 1177 XSR [ENOSTR] | 1178 Not a STREAM. A STREAM function was attempted on a file descriptor that was not 1179 associated with a STREAMS device. 1180 [ENOSYS] 1181 Function not implemented. An attempt was made to use a function that is not available in 1182 this implementation. | 1183 [ENOTCONN] | 1184 Socket not connected. The socket is not connected. | System Interfaces, Issue 6 525 Error Numbers General Information 1185 [ENOTDIR] 1186 Not a directory. A component of the specified path name exists, but it is not a directory, 1187 when a directory was expected. 1188 [ENOTEMPTY] 1189 Directory not empty. A directory other than an empty directory was supplied when an 1190 empty directory was expected. | 1191 [ENOTSOCK] | 1192 Not a socket. The file descriptor does not refer to a socket. | 1193 [ENOTSUP] 1194 Not supported. The implementation does not support this feature of the Realtime Option 1195 Group. 1196 [ENOTTY] 1197 Inappropriate I/O control operation. A control function has been attempted for a file or 1198 special file for which the operation is inappropriate. 1199 [ENXIO] 1200 No such device or address. Input or output on a special file refers to a device that does not 1201 exist, or makes a request beyond the capabilities of the device. It may also occur when, for 1202 example, a tape drive is not on-line. | 1203 [EOPNOTSUPP] | 1204 Operation not supported on socket. The type of socket (address family or protocol) does not 1205 support the requested operation. | 1206 [EOVERFLOW] | 1207 Value too large to be stored in data type. The user ID or group ID of an IPC or file system 1208 object was too large to be stored into the appropriate member of the caller-provided 1209 structure. This error shall only occur on implementations that support a larger range of user 1210 ID or group ID values than the declared structure member can support. This usually occurs 1211 because the IPC or file system object resides on a remote machine with a larger value of the 1212 type uid_t, off_t, or gid_t than the local system. | 1213 [EPERM] 1214 Operation not permitted. An attempt was made to perform an operation limited to 1215 processes with appropriate privileges or to the owner of a file or other resource. 1216 [EPIPE] 1217 Broken pipe. A write was attempted on a socket, pipe, or FIFO for which there is no process | 1218 to read the data. | 1219 [EPROTO] | 1220 Protocol error. Some protocol error occurred. This error is device-specific, but is generally 1221 not related to a hardware failure. | 1222 [EPROTONOSUPPORT] | 1223 Protocol not supported. The protocol is not supported by the address family, or the protocol 1224 is not supported by the implementation. | 1225 [EPROTOTYPE] | 1226 Socket type not supported. The socket type is not supported by the protocol. | 1227 [ERANGE] 1228 Result too large or too small. The result of the function is too large (overflow) or too small 1229 (underflow) to be represented in the available space (defined in the ISO C standard). 526 Technical Standard (2000) (Draft July 31, 2000) General Information Error Numbers 1230 [EROFS] 1231 Read-only file system. An attempt was made to modify a file or directory on a file system 1232 that is read-only. 1233 [ESPIPE] 1234 Invalid seek. An attempt was made to access the file offset associated with a pipe or FIFO. 1235 [ESRCH] 1236 No such process. No process can be found corresponding to that specified by the given 1237 process ID. | 1238 [ESTALE] | 1239 Reserved. | 1240 XSR [ETIME] | 1241 STREAM ioctl( ) timeout. The timer set for a STREAMS ioctl( ) call has expired. The cause of 1242 this error is device-specific and could indicate either a hardware or software failure, or a 1243 timeout value that is too short for the specific operation. The status of the ioctl( ) operation 1244 is indeterminate. | 1245 [ETIMEDOUT] | 1246 Connection timed out. The connection to a remote machine has timed out. If the connection 1247 timed out during execution of the function that reported this error (as opposed to timing 1248 out prior to the function being called), it is unspecified whether the function has completed 1249 some or all of the documented behavior associated with a successful completion of the 1250 function. 1251 or: 1252 Operation timed out. The time limit associated with the operation was exceeded before the | 1253 operation completed. | 1254 [ETXTBSY] | 1255 Text file busy. An attempt was made to execute a pure-procedure program that is currently 1256 open for writing, or an attempt has been made to open for writing a pure-procedure 1257 program that is being executed. | 1258 [EWOULDBLOCK] | 1259 Operation would block. An operation on a socket marked as non-blocking has encountered 1260 a situation such as no data available that otherwise would have caused the function to 1261 suspend execution. 1262 A conforming implementation may assign the same values for [EWOULDBLOCK] and 1263 [EAGAIN]. | 1264 [EXDEV] 1265 Improper link. A link to a file on another file system was attempted. 1266 2.3.1 Additional Error Numbers 1267 Additional implementation-defined error numbers may be defined in . | System Interfaces, Issue 6 527 Signal Concepts General Information 1268 2.4 Signal Concepts 1269 2.4.1 Signal Generation and Delivery 1270 A signal is said to be generated for (or sent to) a process or thread when the event that causes the 1271 signal first occurs. Examples of such events include detection of hardware faults, timer 1272 RTS expiration, signals generated via the sigevent structure and terminal activity, as well as 1273 RTS invocations of kill( ) and sigqueue( ) functions. In some circumstances, the same event generates 1274 signals for multiple processes. 1275 At the time of generation, a determination is made whether the signal has been generated for the 1276 process or for a specific thread within the process. Signals which are generated by some action 1277 attributable to a particular thread, such as a hardware fault, are generated for the thread that 1278 caused the signal to be generated. Signals that are generated in association with a process ID or 1279 process group ID or an asynchronous event such as terminal activity are generated for the 1280 process. 1281 Each process has an action to be taken in response to each signal defined by the system (see 1282 Section 2.4.3 (on page 530)). A signal is said to be delivered to a process when the appropriate 1283 action for the process and signal is taken. A signal is said to be accepted by a process when the 1284 signal is selected and returned by one of the sigwait( ) functions. 1285 During the time between the generation of a signal and its delivery or acceptance, the signal is 1286 said to be pending. Ordinarily, this interval cannot be detected by an application. However, a 1287 signal can be blocked from delivery to a thread. If the action associated with a blocked signal is 1288 anything other than to ignore the signal, and if that signal is generated for the thread, the signal 1289 shall remain pending until it is unblocked, it is accepted when it is selected and returned by a 1290 call to the sigwait( ) function, or the action associated with it is set to ignore the signal. Signals 1291 generated for the process shall be delivered to exactly one of those threads within the process 1292 which is in a call to a sigwait( ) function selecting that signal or has not blocked delivery of the 1293 signal. If there are no threads in a call to a sigwait( ) function selecting that signal, and if all 1294 threads within the process block delivery of the signal, the signal shall remain pending on the 1295 process until a thread calls a sigwait( ) function selecting that signal, a thread unblocks delivery 1296 of the signal, or the action associated with the signal is set to ignore the signal. If the action 1297 associated with a blocked signal is to ignore the signal and if that signal is generated for the 1298 process, it is unspecified whether the signal is discarded immediately upon generation or 1299 remains pending. 1300 Each thread has a signal mask that defines the set of signals currently blocked from delivery to it. 1301 The signal mask for a thread is initialized from that of its parent or creating thread, or from the 1302 corresponding thread in the parent process if the thread was created as the result of a call to 1303 fork( ). The sigaction( ), sigprocmask( ), and sigsuspend( ) functions control the manipulation of the 1304 signal mask. 1305 The determination of which action is taken in response to a signal is made at the time the signal 1306 is delivered, allowing for any changes since the time of generation. This determination is 1307 independent of the means by which the signal was originally generated. If a subsequent 1308 occurrence of a pending signal is generated, it is implementation-defined as to whether the | 1309 RTS signal is delivered or accepted more than once in circumstances other than those in which | 1310 queuing is required under the Realtime Signals Extension option. The order in which multiple, | 1311 simultaneously pending signals outside the range SIGRTMIN to SIGRTMAX are delivered to or | 1312 accepted by a process is unspecified. | 1313 When any stop signal (SIGSTOP, SIGTSTP, SIGTTIN, SIGTTOU) is generated for a process, any 1314 pending SIGCONT signals for that process shall be discarded. Conversely, when SIGCONT is 1315 generated for a process, all pending stop signals for that process shall be discarded. When 528 Technical Standard (2000) (Draft July 31, 2000) General Information Signal Concepts 1316 SIGCONT is generated for a process that is stopped, the process shall be continued, even if the 1317 SIGCONT signal is blocked or ignored. If SIGCONT is blocked and not ignored, it shall remain 1318 pending until it is either unblocked or a stop signal is generated for the process. 1319 An implementation shall document any condition not specified by this volume of 1320 IEEE Std. 1003.1-200x under which the implementation generates signals. | 1321 2.4.2 Realtime Signal Generation and Delivery | 1322 RTS This section describes extensions to support realtime signal generation and delivery. This | 1323 functionality is dependent on support of the Realtime Signals Extension option (and the rest of | 1324 this section is not further shaded for this option). | 1325 Some signal-generating functions, such as high-resolution timer expiration, asynchronous I/O | 1326 completion, interprocess message arrival, and the sigqueue( ) function, support the specification 1327 of an application-defined value, either explicitly as a parameter to the function or in a sigevent 1328 structure parameter. The sigevent structure is defined in and shall contain at least | 1329 the following members: | 1330 _____________________________________________________________________ 1331 _ Member Type Member Name Description ____________________________________________________________________ 1332 int sigev_notify Notification type. 1333 int sigev_signo Signal number. 1334 union sigval sigev_value Signal value. 1335 void(*)(unsigned sigval) sigev_notify_function Notification function. 1336 _ (pthread_attr_t*) sigev_notify_attributes Notification attributes. ____________________________________________________________________ 1337 The sigev_notify member specifies the notification mechanism to use when an asynchronous 1338 event occurs. This volume of IEEE Std. 1003.1-200x defines the following values for the 1339 sigev_notify member: 1340 SIGEV_NONE No asynchronous notification shall be delivered when the event of 1341 interest occurs. 1342 SIGEV_SIGNAL The signal specified in sigev_signo shall be generated for the process when 1343 the event of interest occurs. If the implementation supports the Realtime 1344 Signals Extension option and if the SA_SIGINFO flag is set for that signal 1345 number, then the signal shall be queued to the process and the value 1346 specified in sigev_value shall be the si_value component of the generated 1347 signal. If SA_SIGINFO is not set for that signal number, it is unspecified 1348 whether the signal is queued and what value, if any, is sent. 1349 SIGEV_THREAD A notification function shall be called to perform notification. 1350 An implementation may define additional notification mechanisms. 1351 The sigev_signo member specifies the signal to be generated. The sigev_value member is the 1352 application-defined value to be passed to the signal-catching function at the time of the signal 1353 delivery or to be returned at signal acceptance as the si_value member of the siginfo_t structure. 1354 The sigval union is defined in and contains at least the following members: System Interfaces, Issue 6 529 Signal Concepts General Information 1355 _____________________________________________________ 1356 _ Member Type Member Name Description ____________________________________________________ 1357 int sival_int Integer signal value. 1358 _ void* sival_ptr Pointer signal value. ____________________________________________________ 1359 The sival_int member is used when the application-defined value is of type int; the sival_ptr 1360 member is used when the application-defined value is a pointer. 1361 When a signal is generated by the sigqueue( ) function or any signal-generating function that 1362 supports the specification of an application-defined value, the signal shall be marked pending 1363 and, if the SA_SIGINFO flag is set for that signal, the signal shall be queued to the process along 1364 with the application-specified signal value. Multiple occurrences of signals so generated are 1365 queued in FIFO order. It is unspecified whether signals so generated are queued when the 1366 SA_SIGINFO flag is not set for that signal. 1367 Signals generated by the kill( ) function or other events that cause signals to occur, such as 1368 detection of hardware faults, alarm( ) timer expiration, or terminal activity, and for which the 1369 implementation does not support queuing, have no effect on signals already queued for the 1370 same signal number. 1371 When multiple unblocked signals, all in the range SIGRTMIN to SIGRTMAX, are pending, the 1372 behavior shall be as if the implementation delivers the pending unblocked signal with the lowest 1373 signal number within that range. No other ordering of signal delivery is specified. 1374 If, when a pending signal is delivered, there are additional signals queued to that signal number, 1375 the signal remains pending. Otherwise, the pending indication is reset. 1376 Multi-threaded programs can use an alternate event notification mechanism. When a 1377 notification is processed, and the sigev_notify member of the sigevent structure has the value 1378 SIGEV_THREAD, the function sigev_notify_function is called with parameter sigev_value. 1379 The function shall be executed in an environment as if it were the start_routine for a newly 1380 created thread with thread attributes specified by sigev_notify_attributes. If sigev_notify_attributes 1381 is NULL, the behavior shall be as if the thread were created with the detachstate attribute set to 1382 PTHREAD_CREATE_DETACHED. Supplying an attributes structure with a detachstate attribute 1383 of PTHREAD_CREATE_JOINABLE results in undefined behavior. The signal mask of this 1384 thread is implementation-defined. | 1385 2.4.3 Signal Actions 1386 There are three types of action that can be associated with a signal: SIG_DFL, SIG_IGN, or a 1387 pointer to a function. Initially, all signals shall be set to SIG_DFL or SIG_IGN prior to entry of 1388 the main( ) routine (see the exec functions). The actions prescribed by these values are as follows: 1389 SIG_DFL Signal-specific default action. 1390 The default actions for the signals defined in this volume of IEEE Std. 1003.1-200x 1391 RTS are specified under . If the Realtime Signals Extension option is 1392 supported, the default actions for the realtime signals in the range SIGRTMIN to 1393 SIGRTMAX are to terminate the process abnormally. 1394 If the default action is to stop the process, the execution of that process is 1395 temporarily suspended. When a process stops, a SIGCHLD signal shall be 1396 generated for its parent process, unless the parent process has set the 1397 SA_NOCLDSTOP flag. While a process is stopped, any additional signals that are 1398 sent to the process shall not be delivered until the process is continued, except 1399 SIGKILL which always terminates the receiving process. A process that is a 1400 member of an orphaned process group shall not be allowed to stop in response to 530 Technical Standard (2000) (Draft July 31, 2000) General Information Signal Concepts 1401 the SIGTSTP, SIGTTIN, or SIGTTOU signals. In cases where delivery of one of 1402 these signals would stop such a process, the signal shall be discarded. 1403 Setting a signal action to SIG_DFL for a signal that is pending, and whose default 1404 action is to ignore the signal (for example, SIGCHLD), shall cause the pending 1405 signal to be discarded, whether or not it is blocked. 1406 The default action for SIGCONT is to resume execution at the point where the 1407 RTS process was stopped, after first handling any pending unblocked signals. If the | 1408 Realtime Signals Extension option is supported, any queued values pending shall 1409 be discarded and the resources used to queue them shall be released and returned | 1410 to the system for other use. | 1411 SIG_IGN Ignore signal. 1412 Delivery of the signal shall have no effect on the process. The behavior of a process 1413 RTS is undefined after it ignores a SIGFPE, SIGILL, SIGSEGV, or SIGBUS signal that 1414 RTS was not generated by kill( ),sigqueue( ),or raise( ). 1415 The system shall not allow the action for the signals SIGKILL or SIGSTOP to be set 1416 to SIG_IGN. 1417 Setting a signal action to SIG_IGN for a signal that is pending shall cause the 1418 pending signal to be discarded, whether or not it is blocked. 1419 If a process sets the action for the SIGCHLD signal to SIG_IGN, the behavior is 1420 XSI unspecified, except as specified below. 1421 If the action for the SIGCHLD signal is set to SIG_IGN, child processes of the 1422 calling processes shall not be transformed into zombie processes when they 1423 terminate. If the calling process subsequently waits for its children, and the process 1424 has no unwaited-for children that were transformed into zombie processes, it shall 1425 block until all of its children terminate, and wait( ), waitid( ), and waitpid( ) shall fail | 1426 and set errno to [ECHILD]. 1427 RTS If the Realtime Signals Extension option is supported, any queued values pending 1428 shall be discarded and the resources used to queue them shall be released and 1429 made available to queue other signals. 1430 pointer to a function 1431 Catch signal. 1432 On delivery of the signal, the receiving process is to execute the signal-catching 1433 function at the specified address. After returning from the signal-catching function, 1434 the receiving process shall resume execution at the point at which it was 1435 interrupted. 1436 If the SA_SIGINFO flag for the signal is cleared, the signal-catching function shall 1437 be entered as a C-language function call as follows: 1438 void func(int signo); 1439 XSI|RTS If the SA_SIGINFO flag for the signal is set, the signal-catching function shall be 1440 entered as a C-language function call as follows: 1441 void func(int signo, siginfo_t *info, void *context); 1442 where func is the specified signal-catching function, signo is the signal number of 1443 the signal being delivered, and info is a pointer to a siginfo_t structure defined in 1444 containing at least the following members: System Interfaces, Issue 6 531 Signal Concepts General Information 1445 ___________________________________________________ 1446 _ Member Type Member Name Description __________________________________________________ 1447 int si_signo Signal number 1448 int si_code Cause of the signal 1449 _ union sigval si_value Signal value __________________________________________________ 1450 The si_signo member contains the signal number. This is the same as the signo 1451 parameter. The si_code member contains a code identifying the cause of the signal. 1452 The following values are defined for si_code: 1453 Notes to Reviewers 1454 This section with side shading will not appear in the final copy. - Ed. 1455 The shading in this area needs some work. 1456 XSI|RTS SI_USER The signal was sent by the kill( ) function. The implementation 1457 may set si_code to SI_USER if the signal was sent by the raise( ) or 1458 abort( ) functions or any similar functions provided as 1459 implementation extensions. 1460 RTS SI_QUEUE The signal was sent by the sigqueue( ) function. 1461 RTS SI_TIMER The signal was generated by the expiration of a timer set by 1462 timer_settime( ). 1463 RTS SI_ASYNCIO The signal was generated by the completion of an asynchronous 1464 I/O request. 1465 RTS SI_MESGQ The signal was generated by the arrival of a message on an 1466 empty message queue. 1467 If the signal was not generated by one of the functions or events listed above, the 1468 si_code shall be set to an implementation-defined value that is not equal to any of | 1469 the values defined above. 1470 RTS If the Realtime Signals Extension is supported, and si_code is one of SI_QUEUE, 1471 SI_TIMER, SI_ASYNCIO, or SI_MESGQ, then si_value contains the application- 1472 specified signal value. Otherwise, the contents of si_value are undefined. 1473 The behavior of a process is undefined after it returns normally from a signal- 1474 XSI catching function for a SIGBUS, SIGFPE, SIGILL, or SIGSEGV signal that was not 1475 RTS generated by kill( ),sigqueue( ),or raise( ). 1476 The system shall not allow a process to catch the signals SIGKILL and SIGSTOP. 1477 If a process establishes a signal-catching function for the SIGCHLD signal while it 1478 has a terminated child process for which it has not waited, it is unspecified 1479 whether a SIGCHLD signal is generated to indicate that child process. 1480 When signal-catching functions are invoked asynchronously with process 1481 execution, the behavior of some of the functions defined by this volume of 1482 IEEE Std. 1003.1-200x is unspecified if they are called from a signal-catching 1483 function. 1484 The following table defines a set of functions that are either reentrant or not 1485 interruptible by signals and are async-signal-safe. Therefore applications may 1486 invoke them, without restriction, from signal-catching functions: 532 Technical Standard (2000) (Draft July 31, 2000) General Information Signal Concepts 1487 Notes to Reviewers 1488 This section with side shading will not appear in the final copy. - Ed. 1489 The contents of the following tables need to be reviewed. 1490 Base functions: 1491 _Exit( ) fpathconf( ) pipe( ) stat( ) 1492 _exit( ) fstat( ) raise( ) symlink( ) 1493 access( ) fsync( ) read( ) sysconf( ) 1494 alarm( ) ftruncate( ) readlink( ) tcdrain( ) 1495 cfgetispeed( ) getegid( ) rename( ) tcflow( ) 1496 cfgetospeed( ) geteuid( ) rmdir( ) tcflush( ) 1497 cfsetispeed( ) getgid( ) setgid( ) tcgetattr( ) 1498 cfsetospeed( ) getgroups( ) setpgid( ) tcgetpgrp( ) 1499 chdir( ) getpgrp( ) setsid( ) tcsendbreak( ) 1500 chmod( ) getpid( ) setuid( ) tcsetattr( ) 1501 chown( ) getppid( ) sigaction( ) tcsetpgrp( ) 1502 close( ) getuid( ) sigaddset( ) time( ) 1503 creat( ) kill( ) sigdelset( ) times( ) 1504 dup( ) link( ) sigemptyset( ) umask( ) 1505 dup2( ) lseek( ) sigfillset( ) uname( ) 1506 execle( ) lstat( ) sigismember( ) unlink( ) 1507 execve( ) mkdir( ) signal( ) utime( ) 1508 fchmod( ) mkfifo( ) sigpending( ) wait( ) 1509 fchown( ) open( ) sigprocmask( ) waitpid( ) 1510 fcntl( ) pathconf( ) sigsuspend( ) write( ) 1511 fork( ) pause( ) sleep( ) 1512 Realtime functions: 1513 aio_error( ) clock_gettime( ) sigpause( ) timer_getoverrun( ) 1514 aio_return( ) fdatasync( ) sigqueue( ) timer_gettime( ) 1515 aio_suspend( ) sem_post( ) sigset( ) timer_settime( ) 1516 Tracing functions: | 1517 posix_trace_event( )| || 1518 All functions not in the above table are considered to be unsafe with respect to | 1519 signals. In the presence of signals, all functions defined by this volume of 1520 IEEE Std. 1003.1-200x shall behave as defined when called from or interrupted by a 1521 signal-catching function, with a single exception: when a signal interrupts an 1522 unsafe function and the signal-catching function calls an unsafe function, the 1523 behavior is undefined. 1524 When a signal is delivered to a thread, if the action of that signal specifies termination, stop, or 1525 continue, the entire process shall be terminated, stopped, or continued, respectively. System Interfaces, Issue 6 533 Signal Concepts General Information 1526 2.4.4 Signal Effects on Other Functions 1527 Signals affect the behavior of certain functions defined by this volume of IEEE Std. 1003.1-200x if 1528 delivered to a process while it is executing such a function. If the action of the signal is to 1529 terminate the process, the process shall be terminated and the function shall not return. If the 1530 action of the signal is to stop the process, the process shall stop until continued or terminated. 1531 Generation of a SIGCONT signal for the process shall cause the process to be continued, and the 1532 original function shall continue at the point the process was stopped. If the action of the signal is 1533 to invoke a signal-catching function, the signal-catching function shall be invoked; in this case 1534 the original function is said to be interrupted by the signal. | 1535 Notes to Reviewers | 1536 This section with side shading will not appear in the final copy. - Ed. | 1537 D3, XSH, ERN 20 points out a discrepancy between the following sentence and the paragraph | 1538 above beginning "All functions not in the above ...". An interpretation will be filed. | 1539 If the signal-catching function executes a return statement, the behavior of the interrupted | 1540 function shall be as described individually for that function. Signals that are ignored shall not 1541 affect the behavior of any function; signals that are blocked shall not affect the behavior of any 1542 function until they are unblocked and then delivered, except as specified for the sigpending( ) and 1543 sigwait( ) functions. 534 Technical Standard (2000) (Draft July 31, 2000) General Information Standard I/O Streams 1544 2.5 Standard I/O Streams 1545 A stream is associated with an external file (which may be a physical device) by opening a file, 1546 which may involve creating a new file. Creating an existing file causes its former contents to be 1547 discarded if necessary. If a file can support positioning requests, (such as a disk file, as opposed 1548 to a terminal), then a file position indicator associated with the stream is positioned at the start 1549 (byte number 0) of the file, unless the file is opened with append mode, in which case it is | 1550 implementation-defined whether the file position indicator is initially positioned at the | 1551 beginning or end of the file. The file position indicator is maintained by subsequent reads, 1552 writes, and positioning requests, to facilitate an orderly progression through the file. All input 1553 takes place as if bytes were read by successive calls to fgetc( ); all output takes place as if bytes 1554 were written by successive calls to fputc( ). 1555 When a stream is unbuffered, bytes are intended to appear from the source or at the destination 1556 as soon as possible; otherwise, bytes may be accumulated and transmitted as a block. When a 1557 stream is fully buffered, bytes are intended to be transmitted as a block when a buffer is filled. 1558 When a stream is line buffered, bytes are intended to be transmitted as a block when a newline 1559 byte is encountered. Furthermore, bytes are intended to be transmitted as a block when a buffer 1560 is filled, when input is requested on an unbuffered stream, or when input is requested on a line- 1561 buffered stream that requires the transmission of bytes. Support for these characteristics is | 1562 implementation-defined, and may be affected via setbuf( ) and setvbuf( ). | 1563 A file may be disassociated from a controlling stream by closing the file. Output streams are 1564 flushed (any unwritten buffer contents are transmitted) before the stream is disassociated from 1565 the file. The value of a pointer to a FILE object is indeterminate after the associated file is closed 1566 (including the standard streams). 1567 A file may be subsequently reopened, by the same or another program execution, and its 1568 contents reclaimed or modified (if it can be repositioned at its start). If the main( ) function 1569 returns to its original caller, or if the exit( ) function is called, all open files are closed (hence all 1570 output streams are flushed) before program termination. Other paths to program termination, 1571 such as calling abort( ), need not close all files properly. 1572 The address of the FILE object used to control a stream may be significant; a copy of a FILE 1573 object need not necessarily serve in place of the original. 1574 At program start-up, three streams are predefined and need not be opened explicitly: standard | 1575 input (for reading conventional input), standard output (for writing conventional output), and 1576 standard error (for writing diagnostic output). When opened, the standard error stream is not 1577 fully buffered; the standard input and standard output streams are fully buffered if and only if 1578 the stream can be determined not to refer to an interactive device. 1579 2.5.1 Interaction of File Descriptors and Standard I/O Streams 1580 CX This section describes the interaction of file descriptors and standard I/O streams. This | 1581 functionality is an extension to the ISO C standard (and the rest of this section is not further CX | 1582 shaded). | 1583 An open file description may be accessed through a file descriptor, which is created using | 1584 functions such as open( ) or pipe( ), or through a stream, which is created using functions such as 1585 fopen( ) or popen( ). Either a file descriptor or a stream is called a handle on the open file | 1586 description to which it refers; an open file description may have several handles. 1587 Handles can be created or destroyed by explicit user action, without affecting the underlying 1588 open file description. Some of the ways to create them include fcntl( ), dup( ), fdopen( ), fileno( ), 1589 and fork( ). They can be destroyed by at least fclose( ), close( ), and the exec functions. System Interfaces, Issue 6 535 Standard I/O Streams General Information 1590 A file descriptor that is never used in an operation that could affect the file offset (for example, 1591 read( ), write( ), or lseek( )) is not considered a handle for this discussion, but could give rise to one 1592 (for example, as a consequence of fdopen( ), dup( ), or fork( )). This exception does not include the | 1593 file descriptor underlying a stream, whether created with fopen( ) or fdopen( ), so long as it is not 1594 used directly by the application to affect the file offset. The read( ) and write( ) functions 1595 implicitly affect the file offset; lseek( ) explicitly affects it. 1596 The result of function calls involving any one handle (the active handle) is defined elsewhere in 1597 this volume of IEEE Std. 1003.1-200x, but if two or more handles are used, and any one of them is 1598 a stream, the application shall ensure that their actions are coordinated as described below. If 1599 this is not done, the result is undefined. 1600 A handle which is a stream is considered to be closed when either an fclose( ) or freopen( ) is 1601 executed on it (the result of freopen( ) is a new stream, which cannot be a handle on the same 1602 open file description as its previous value), or when the process owning that stream terminates 1603 with exit( ) or abort( ). A file descriptor is closed by close( ), _exit( ), or the exec functions when 1604 FD_CLOEXEC is set on that file descriptor. 1605 For a handle to become the active handle, the application shall ensure that the actions below are 1606 performed between the last use of the handle (the current active handle) and the first use of the 1607 second handle (the future active handle). The second handle then becomes the active handle. All 1608 activity by the application affecting the file offset on the first handle shall be suspended until it 1609 again becomes the active file handle. (If a stream function has as an underlying function one that 1610 affects the file offset, the stream function shall be considered to affect the file offset.) 1611 The handles need not be in the same process for these rules to apply. 1612 Note that after a fork( ), two handles exist where one existed before. The application shall ensure 1613 that, if both handles can ever be accessed, they are both in a state where the other could become 1614 the active handle first. The application shall prepare for a fork( ) exactly as if it were a change of 1615 active handle. (If the only action performed by one of the processes is one of the exec functions or 1616 _exit( ) (not exit( )), the handle is never accessed in that process.) 1617 For the first handle, the first applicable condition below applies. After the actions required 1618 below are taken, if the handle is still open, the application can close it. 1619 * If it is a file descriptor, no action is required. 1620 * If the only further action to be performed on any handle to this open file descriptor is to close 1621 it, no action need be taken. 1622 * If it is a stream which is unbuffered, no action need be taken. 1623 * If it is a stream which is line buffered, and the last byte written to the stream was a newline 1624 (that is, as if a: 1625 putc('\n') 1626 was the most recent operation on that stream), no action need be taken. 1627 * If it is a stream which is open for writing or appending (but not also open for reading), the 1628 application shall either perform an fflush( ), or the stream shall be closed. 1629 * If the stream is open for reading and it is at the end of the file (feof( ) is true), no action need 1630 be taken. 1631 * If the stream is open with a mode that allows reading and the underlying open file 1632 description refers to a device that is capable of seeking, the application shall either perform 1633 an fflush( ), or the stream shall be closed. 536 Technical Standard (2000) (Draft July 31, 2000) General Information Standard I/O Streams 1634 Otherwise, the result is undefined. 1635 For the second handle: 1636 * If any previous active handle has been used by a function that explicitly changed the file 1637 offset, except as required above for the first handle, the application shall perform an lseek( ) or 1638 fseek( ) (as appropriate to the type of handle) to an appropriate location. 1639 If the active handle ceases to be accessible before the requirements on the first handle, above, 1640 have been met, the state of the open file description becomes undefined. This might occur during 1641 functions such as a fork( ) or _exit( ). 1642 The exec functions make inaccessible all streams that are open at the time they are called, 1643 independent of which streams or file descriptors may be available to the new process image. 1644 When these rules are followed, regardless of the sequence of handles used, implementations 1645 shall ensure that an application, even one consisting of several processes, shall yield correct 1646 results: no data shall be lost or duplicated when writing, and all data shall be written in order, | 1647 except as requested by seeks. It is implementation-defined whether, and under what conditions, | 1648 all input is seen exactly once. 1649 If the rules above are not followed, the result is unspecified. 1650 Each function that operates on a stream is said to have zero or more underlying functions. This 1651 means that the stream function shares certain traits with the underlying functions, but does not 1652 require that there be any relation between the implementations of the stream function and its 1653 underlying functions. 1654 2.5.2 Stream Orientation and Encoding Rules 1655 For conformance to the ISO/IEC 9899: 1999 standard, the definition of a stream includes an | 1656 orientation. After a stream is associated with an external file, but before any operations are 1657 performed on it, the stream is without orientation. Once a wide-character input/output function 1658 has been applied to a stream without orientation, the stream shall become wide-oriented. 1659 Similarly, once a byte input/output function has been applied to a stream without orientation, 1660 the stream shall become byte-oriented. Only a call to the freopen( ) function or the fwide( ) function 1661 can otherwise alter the orientation of a stream. 1662 A successful call to freopen( ) shall remove any orientation. The three predefined streams standard 1663 input, standard output, and standard error shall be unoriented at program start-up. 1664 Byte input/output functions cannot be applied to a wide-oriented stream, and wide-character 1665 input/output functions cannot be applied to a byte-oriented stream. The remaining stream 1666 operations shall not affect and shall not be affected by a stream's orientation, except for the 1667 following additional restrictions: 1668 * Binary wide-oriented streams have the file positioning restrictions ascribed to both text and 1669 binary streams. 1670 * For wide-oriented streams, after a successful call to a file-positioning function that leaves the 1671 file position indicator prior to the end-of-file, a wide-character output function can overwrite 1672 a partial character; any file contents beyond the byte(s) written are henceforth undefined. 1673 Each wide-oriented stream has an associated mbstate_t object that stores the current parse state 1674 of the stream. A successful call to fgetpos( ) shall store a representation of the value of this 1675 mbstate_t object as part of the value of the fpos_t object. A later successful call to fsetpos( ) using 1676 the same stored fpos_t value shall restore the value of the associated mbstate_t object as well as 1677 the position within the controlled stream. System Interfaces, Issue 6 537 Standard I/O Streams General Information 1678 Implementations that support multiple encoding rules associate an encoding rule with the 1679 stream. The encoding rule shall be determined by the setting of the LC_CTYPE category in the 1680 current locale at the time when the stream becomes wide-oriented. If a wide-character 1681 input/output function is applied to a byte-oriented stream, the encoding rule used is undefined. 1682 As with the stream's orientation, the encoding rule associated with a stream cannot be changed 1683 once it has been set, except by a successful call to freopen( ) which clears the encoding rule and 1684 resets the orientation to unoriented. 1685 Although both text and binary wide-oriented streams are conceptually sequences of wide 1686 characters, the external file associated with a wide-oriented stream is a sequence of (possibly 1687 multibyte) characters generalized as follows: 1688 * Multibyte encodings within files may contain embedded null bytes (unlike multibyte 1689 encodings valid for use internal to the program). 1690 * A file need not begin nor end in the initial shift state. 1691 Moreover, the encodings used for characters may differ among files. Both the nature and choice 1692 of such encodings are implementation-defined. | 1693 The wide-character input functions read characters from the stream and convert them to wide 1694 characters as if they were read by successive calls to the fgetwc( ) function. Each conversion shall 1695 occur as if by a call to the mbrtowc( ) function, with the conversion state described by the stream's 1696 CX own mbstate_t object, except the encoding rule associated with the stream is used instead of the 1697 encoding rule implied by the LC_CTYPE category of the current locale. 1698 The wide-character output functions convert wide characters to (possibly multibyte) characters 1699 and write them to the stream as if they were written by successive calls to the fputwc( ) function. 1700 Each conversion shall occur as if by a call to the wcrtomb( ) function, with the conversion state 1701 CX described by the stream's own mbstate_t object, except the encoding rule associated with the 1702 stream is used instead of the encoding rule implied by the LC_CTYPE category of the current 1703 locale. 1704 An encoding error shall occur if the character sequence presented to the underlying mbrtowc( ) 1705 function does not form a valid (generalized) character, or if the code value passed to the 1706 underlying wcrtomb( ) function does not correspond to a valid (generalized) character. The 1707 wide-character input/output functions and the byte input/output functions store the value of 1708 the macro EILSEQ in errno if and only if an encoding error occurs. 538 Technical Standard (2000) (Draft July 31, 2000) General Information STREAMS 1709 2.6 STREAMS 1710 XSR STREAMS functionality is provided on implementations supporting the XSI STREAMS Option | 1711 Group. This functionality is dependent on support of the XSI STREAMS option (and the rest of | 1712 this section is not further shaded for this option). | 1713 STREAMS provides a uniform mechanism for implementing networking services and other | 1714 character-based I/O. The STREAMS function provides direct access to protocol modules. A 1715 STREAM is typically a full-duplex connection between a process and an open device or pseudo- 1716 device. However, since pipes may be STREAMS-based, a STREAM can be a full-duplex 1717 connection between two processes. The STREAM itself exists entirely within the implementation 1718 and provides a general character I/O function for processes. It optionally includes one or more 1719 intermediate processing modules that are interposed between the process end of the STREAM 1720 (STREAM head) and a device driver at the end of the STREAM (STREAM end). 1721 STREAMS I/O is based on messages. Messages flow in both directions in a STREAM. A given 1722 module need not understand and process every message in the STREAM, but every module in 1723 the STREAM handles every message. Each module accepts messages from one of its neighbor 1724 modules in the STREAM, and passes them to the other neighbor. For example, a line discipline 1725 module may transform the data. Data flow through the intermediate modules is bidirectional, 1726 with all modules handling, and optionally processing, all messages. There are three types of 1727 messages: 1728 * Data messages containing actual data for input or output 1729 * Control data containing instructions for the STREAMS modules and underlying 1730 implementation 1731 * Other messages, which include file descriptors 1732 The function between the STREAM and the rest of the implementation is provided by a set of 1733 functions at the STREAM head. When a process calls write( ), putmsg( ), putpmsg( ), or ioctl( ), 1734 messages are sent down the STREAM, and read( ), getmsg( ), or getpmsg( ) accepts data from the 1735 STREAM and passes it to a process. Data intended for the device at the downstream end of the 1736 STREAM is packaged into messages and sent downstream, while data and signals from the 1737 device are composed into messages by the device driver and sent upstream to the STREAM 1738 head. 1739 When a STREAMS-based device is opened, a STREAM is created that contains two modules: the 1740 STREAM head module and the STREAM end (driver) module. If pipes are STREAMS-based in 1741 an implementation, when a pipe is created, two STREAMS are created, each containing a 1742 STREAM head module. Other modules are added to the STREAM using ioctl( ). New modules 1743 are ``pushed'' onto the STREAM one at a time in last-in, first-out (LIFO) style, as though the 1744 STREAM was a push-down stack. | 1745 Priority 1746 Message types are classified according to their queuing priority and may be normal (non- | 1747 priority), priority, or high-priority messages. A message belongs to a particular priority band that 1748 determines its ordering when placed on a queue. Normal messages have a priority band of 0 and 1749 are always placed at the end of the queue following all other messages in the queue. High- 1750 priority messages are always placed at the head of a queue, but are discarded if there is already a 1751 high-priority message in the queue. Their priority band is ignored; they are high-priority by 1752 virtue of their type. Priority messages have a priority band greater than 0. Priority messages are 1753 always placed after any messages of the same or higher priority. High-priority and priority 1754 messages are used to send control and data information outside the normal flow of control. By 1755 convention, high-priority messages are not affected by flow control. Normal and priority System Interfaces, Issue 6 539 STREAMS General Information 1756 messages have separate flow controls. | 1757 Message Parts 1758 A process may access STREAMS messages that contain a data part, control part, or both. The | 1759 data part is that information which is transmitted over the communication medium and the 1760 control information is used by the local STREAMS modules. The other types of messages are 1761 used between modules and are not accessible to processes. Messages containing only a data part 1762 are accessible via putmsg( ), putpmsg( ), getmsg( ), getpmsg( ), read( ), or write( ). Messages 1763 containing a control part with or without a data part are accessible via calls to putmsg( ), 1764 putpmsg( ), getmsg( ), or getpmsg( ). | 1765 2.6.1 Accessing STREAMS 1766 A process accesses STREAMS-based files using the standard functions close( ), ioctl( ), getmsg( ), | 1767 getpmsg( ), open( ), pipe( ), poll( ), putmsg( ), putpmsg( ), read( ), or write( ). Refer to the applicable 1768 function definitions for general properties and errors. 1769 Calls to ioctl( ) are used to perform control functions with the STREAMS-based device associated 1770 with the file descriptor fildes. The arguments command and arg are passed to the STREAMS file 1771 designated by fildes and are interpreted by the STREAM head. Certain combinations of these 1772 arguments may be passed to a module or driver in the STREAM. 1773 Since these STREAMS requests are a subset of ioctl( ), they are subject to the errors described 1774 there. 1775 STREAMS modules and drivers can detect errors, sending an error message to the STREAM 1776 head, thus causing subsequent functions to fail and set errno to the value specified in the 1777 message. In addition, STREAMS modules and drivers can elect to fail a particular ioctl( ) request 1778 alone by sending a negative acknowledgement message to the STREAM head. This causes just 1779 the pending ioctl( ) request to fail and set errno to the value specified in the message. | 540 Technical Standard (2000) (Draft July 31, 2000) General Information XSI Interprocess Communication 1780 2.7 XSI Interprocess Communication 1781 XSI This section describes extensions to support interprocess communication. This functionality is | 1782 dependent on support of the XSI Extension (and the rest of this section is not further shaded for | 1783 this option). | 1784 The following message passing, semaphore, and shared memory services form an XSI | 1785 interprocess communication facility. Certain aspects of their operation are common, and are 1786 described below. 1787 ________________________________ 1788 _ IPC Functions _______________________________ 1789 msgctl( ) semctl( ) shmctl( ) 1790 msgget( ) semget( ) shmdt( ) 1791 msgrcv( ) semop( ) shmget( ) 1792 msgsnd( ) shmat( ) _ _______________________________ 1793 Another interprocess communication facility is provided by functions in the Realtime Option 1794 Group; see Section 2.8 (on page 543). | 1795 2.7.1 IPC General Description 1796 Each individual shared memory segment, message queue, and semaphore set is identified by a | 1797 unique positive integer, called respectively a shared memory identifier, shmid, a semaphore 1798 identifier, semid, and a message queue identifier, msqid. The identifiers are returned by calls to 1799 shmget( ), semget( ), and msgget( ), respectively. 1800 Associated with each identifier is a data structure which contains data related to the operations 1801 which may be or may have been performed; see the Base Definitions volume of | 1802 IEEE Std. 1003.1-200x, , , and for their descriptions. | 1803 Each of the data structures contains both ownership information and an ipc_perm structure (see | 1804 the Base Definitions volume of IEEE Std. 1003.1-200x, ) which are used in conjunction | 1805 to determine whether or not read/write (read/alter for semaphores) permissions should be 1806 granted to processes using the IPC facilities. The mode member of the ipc_perm structure acts as 1807 a bit field which determines the permissions. 1808 The values of the bits are given below in octal notation. 1809 _______________________ 1810 _ Bit Meaning ______________________ 1811 0400 Read by user. 1812 0200 Write by user. 1813 0040 Read by group. 1814 0020 Write by group. 1815 0004 Read by others. 1816 _ 0002 Write by others. ______________________ 1817 The name of the ipc_perm structure is shm_perm, sem_perm, or msg_perm, depending on which 1818 service is being used. In each case, read and write/alter permissions are granted to a process if 1819 one or more of the following are true ("xxx" is replaced by shm, sem, or msg, as appropriate): 1820 * The process has appropriate privileges. 1821 * The effective user ID of the process matches xxx_perm.cuid or xxx_perm.uid in the data 1822 structure associated with the IPC identifier, and the appropriate bit of the user field in 1823 xxx_perm.mode is set. System Interfaces, Issue 6 541 XSI Interprocess Communication General Information 1824 * The effective user ID of the process does not match xxx_perm.cuid or xxx_perm.uid but the 1825 effective group ID of the process matches xxx_perm.cgid or xxx_perm.gid in the data structure 1826 associated with the IPC identifier, and the appropriate bit of the group field in xxx_perm.mode 1827 is set. 1828 * The effective user ID of the process does not match xxx_perm.cuid or xxx_perm.uid and the 1829 effective group ID of the process does not match xxx_perm.cgid or xxx_perm.gid in the data 1830 structure associated with the IPC identifier, but the appropriate bit of the other field in 1831 xxx_perm.mode is set. 1832 Otherwise, the permission is denied. | 542 Technical Standard (2000) (Draft July 31, 2000) General Information Realtime 1833 2.8 Realtime 1834 This section defines functions to support the source portability of applications with realtime | 1835 requirements. The presence of many of these functions is dependent on support for 1836 implementation options described in the text. 1837 The specific functional areas included in this section and their scope include the following. Full 1838 definitions of these terms can be found in the Base Definitions volume of IEEE Std. 1003.1-200x, | 1839 Chapter 3, Definitions. | 1840 * Semaphores 1841 * Process Memory Locking 1842 * Memory Mapped Files and Shared Memory Objects 1843 * Priority Scheduling 1844 * Realtime Signal Extension 1845 * Timers 1846 * Interprocess Communication 1847 * Synchronized Input and Output 1848 * Asynchronous Input and Output 1849 All the realtime functions defined in this volume of IEEE Std. 1003.1-200x are portable, although 1850 some of the numeric parameters used by an implementation may have hardware dependencies. | 1851 2.8.1 Realtime Signals | 1852 RTS Realtime signal generation and delivery is dependent on support for the Realtime Signals | 1853 Extension option. 1854 See Section 2.4.2 (on page 529). | 1855 2.8.2 Asynchronous I/O 1856 AIO The functionality described in this section is dependent on support of the Asynchronous Input | 1857 and Output option (and the rest of this section is not further shaded for this option). | 1858 An asynchronous I/O control block structure aiocb is used in many asynchronous I/O | 1859 functions. It is defined in the Base Definitions volume of IEEE Std. 1003.1-200x, and has | 1860 at least the following members: ___________________________________________________________ 1861 _ Member Type Member Name Description __________________________________________________________ 1862 int aio_fildes File descriptor. 1863 off_t aio_offset File offset. 1864 volatile void* aio_buf Location of buffer. 1865 size_t aio_nbytes Length of transfer. 1866 int aio_reqprio Request priority offset. 1867 struct sigevent aio_sigevent Signal number and value. 1868 _ int aio_lio_opcode Operation to be performed. __________________________________________________________ 1869 The aio_fildes element is the file descriptor on which the asynchronous operation is performed. 1870 If O_APPEND is not set for the file descriptor aio_fildes and if aio_fildes is associated with a | 1871 device that is capable of seeking, then the requested operation takes place at the absolute 1872 position in the file as given by aio_offset , as if lseek( ) were called immediately prior to the System Interfaces, Issue 6 543 Realtime General Information 1873 operation with an offset argument equal to aio_offset and a whence argument equal to SEEK_SET. 1874 If O_APPEND is set for the file descriptor, or if aio_fildes is associated with a device that is 1875 incapable of seeking, write operations append to the file in the same order as the calls were 1876 made, with the following exception: under implementation-defined circumstances, such as | 1877 operation on a multiprocessor or when requests of differing priorities are submitted at the same 1878 time, the ordering restriction may be relaxed. After a successful call to enqueue an asynchronous 1879 I/O operation, the value of the file offset for the file is unspecified. The aio_nbytes and aio_buf 1880 elements are the same as the nbyte and buf arguments defined by read( ) and write( ), respectively. 1881 If _POSIX_PRIORITIZED_IO and _POSIX_PRIORITY_SCHEDULING are defined, then 1882 asynchronous I/O is queued in priority order, with the priority of each asynchronous operation 1883 based on the current scheduling priority of the calling process. The aio_reqprio member can be 1884 used to lower (but not raise) the asynchronous I/O operation priority and is within the range 1885 zero through {AIO_PRIO_DELTA_MAX}, inclusive. Unless both _POSIX_PRIORITIZED_IO and 1886 _POSIX_PRIORITY_SCHEDULING are defined, the order of processing asynchronous I/O 1887 requests is unspecified. When both _POSIX_PRIORITIZED_IO and 1888 _POSIX_PRIORITY_SCHEDULING are defined, the order of processing of requests submitted 1889 by processes whose schedulers are not SCHED_FIFO, SCHED_RR, or SCHED_SPORADIC is 1890 unspecified. The priority of an asynchronous request is computed as (process scheduling 1891 priority) minus aio_reqprio. The priority assigned to each asynchronous I/O request is an 1892 indication of the desired order of execution of the request relative to other asynchronous I/O 1893 requests for this file. If _POSIX_PRIORITIZED_IO is defined, requests issued with the same 1894 priority to a character special file are processed by the underlying device in FIFO order; the order 1895 of processing of requests of the same priority issued to files that are not character special files is 1896 unspecified. Numerically higher priority values indicate requests of higher priority. The value of 1897 aio_reqprio has no effect on process scheduling priority. When prioritized asynchronous I/O 1898 requests to the same file are blocked waiting for a resource required for that I/O operation, the 1899 higher-priority I/O requests shall be granted the resource before lower-priority I/O requests are 1900 granted the resource. The relative priority of asynchronous I/O and synchronous I/O is | 1901 implementation-defined. If _POSIX_PRIORITIZED_IO is defined, the implementation shall | 1902 define for which files I/O prioritization is supported. 1903 The aio_sigevent determines how the calling process shall be notified upon I/O completion, as 1904 specified in Section 2.4.1 (on page 528). If aio_sigevent.sigev_notify is SIGEV_NONE, then no 1905 signal shall be posted upon I/O completion, but the error status for the operation and the return 1906 status for the operation shall be set appropriately. 1907 The aio_lio_opcode field is used only by the lio_listio ( ) call. The lio_listio ( ) call allows multiple 1908 asynchronous I/O operations to be submitted at a single time. The function takes as an 1909 argument an array of pointers to aiocb structures. Each aiocb structure indicates the operation to 1910 be performed (read or write) via the aio_lio_opcode field. 1911 The address of the aiocb structure is used as a handle for retrieving the error status and return 1912 status of the asynchronous operation while it is in progress. 1913 The aiocb structure and the data buffers associated with the asynchronous I/O operation are 1914 being used by the system for asynchronous I/O while, and only while, the error status of the 1915 asynchronous operation is equal to EINPROGRESS. Applications shall not modify the aiocb 1916 structure while the structure is being used by the system for asynchronous I/O. 1917 The return status of the asynchronous operation is the number of bytes transferred by the I/O 1918 operation. If the error status is set to indicate an error completion, then the return status is set to 1919 the return value that the corresponding read( ), write( ), or fsync( ) call would have returned. 1920 When the error status is not equal to EINPROGRESS, the return status shall reflect the return 1921 status of the corresponding synchronous operation. 544 Technical Standard (2000) (Draft July 31, 2000) General Information Realtime 1922 2.8.3 Memory Management 1923 2.8.3.1 Memory Locking | 1924 ML The functionality described in this section is dependent on support of the Process Memory | 1925 Locking option (and the rest of this section is not further shaded for this option). | 1926 Range memory locking operations are defined in terms of pages. Implementations may restrict | 1927 the size and alignment of range lockings to be on page-size boundaries. The page size, in bytes, | 1928 is the value of the configurable system variable {PAGESIZE}. If an implementation has no | 1929 restrictions on size or alignment, it may specify a 1-byte page size. 1930 Memory locking guarantees the residence of portions of the address space. It is | 1931 implementation-defined whether locking memory guarantees fixed translation between virtual | 1932 addresses (as seen by the process) and physical addresses. Per-process memory locks are not 1933 inherited across a fork( ), and all memory locks owned by a process are unlocked upon exec or 1934 process termination. Unmapping of an address range removes any memory locks established on 1935 that address range by this process. | 1936 2.8.3.2 Memory Mapped Files | 1937 MF The functionality described in this section is dependent on support of the Memory Mapped Files | 1938 option (and the rest of this section is not further shaded for this option). | 1939 Range memory mapping operations are defined in terms of pages. Implementations may | 1940 restrict the size and alignment of range mappings to be on page-size boundaries. The page size, | 1941 in bytes, is the value of the configurable system variable {PAGESIZE}. If an implementation has | 1942 no restrictions on size or alignment, it may specify a 1-byte page size. | 1943 Memory mapped files provide a mechanism that allows a process to access files by directly | 1944 incorporating file data into its address space. Once a file is mapped into a process address space, 1945 the data can be manipulated as memory. If more than one process maps a file, its contents are 1946 shared among them. If the mappings allow shared write access, then data written into the 1947 memory object through the address space of one process appears in the address spaces of all 1948 processes that similarly map the same portion of the memory object. 1949 SHM Shared memory objects are named regions of storage that may be independent of the file system 1950 and can be mapped into the address space of one or more processes to allow them to share the 1951 associated memory. 1952 SHM An unlink( ) of a file or shm_unlink( ) of a shared memory object,while causing the removal of the 1953 name, does not unmap any mappings established for the object. Once the name has been 1954 removed, the contents of the memory object are preserved as long as it is referenced. The 1955 memory object remains referenced as long as a process has the memory object open or has some 1956 area of the memory object mapped. | 1957 2.8.3.3 Memory Protection | 1958 MPR MF The functionality described in this section is dependent on support of the Memory Protection | 1959 and Memory Mapped Files option (and the rest of this section is not further shaded for these | 1960 options). | 1961 When an object is mapped, various application accesses to the mapped region may result in | 1962 signals. In this context, SIGBUS is used to indicate an error using the mapped object, and | 1963 SIGSEGV is used to indicate a protection violation or misuse of an address: | 1964 * A mapping may be restricted to disallow some types of access. | System Interfaces, Issue 6 545 Realtime General Information 1965 * Write attempts to memory that was mapped without write access, or any access to memory | 1966 mapped PROT_NONE, shall result in a SIGSEGV signal. | 1967 * References to unmapped addresses shall result in a SIGSEGV signal. | 1968 * Reference to whole pages within the mapping, but beyond the current length of the object, | 1969 shall result in a SIGBUS signal. | 1970 * The size of the object is unaffected by access beyond the end of the object (even if a SIGBUS is | 1971 not generated). | 1972 2.8.3.4 Typed Memory Objects | 1973 TYM The functionality described in this section is dependent on support of the Typed Memory | 1974 Objects option (and the rest of this section is not further shaded for this option). | 1975 Implementations may support the Typed Memory Objects option without supporting the | 1976 Memory Mapped Files option or the Shared Memory Objects option. Typed memory objects are 1977 implementation-configurable named storage pools accessible from one or more processors in a 1978 system, each via one or more ports, such as backplane buses, LANs, I/O channels, and so on. 1979 Each valid combination of a storage pool and a port is identified through a name that is defined 1980 at system configuration time, in an implementation-defined manner; the name may be | 1981 independent of the file system. Using this name, a typed memory object can be opened and | 1982 mapped into process address space. For a given storage pool and port, it is necessary to support 1983 both dynamic allocation from the pool as well as mapping at an application-supplied offset 1984 within the pool; when dynamic allocation has been performed, subsequent deallocation must be 1985 supported. Lastly, accessing typed memory objects from different ports requires a method for 1986 obtaining the offset and length of contiguous storage of a region of typed memory (dynamically 1987 allocated or not); this allows typed memory to be shared among processes and/or processors 1988 while being accessed from the desired port. | 1989 2.8.4 Process Scheduling 1990 Scheduling Policies 1991 PS The functionality described in this section is dependent on support of the Process Scheduling | 1992 option (and the rest of this section is not further shaded for this option). | 1993 The scheduling semantics described in this volume of IEEE Std. 1003.1-200x are defined in terms 1994 of a conceptual model that contains a set of thread lists. No implementation structures are 1995 necessarily implied by the use of this conceptual model. It is assumed that no time elapses 1996 during operations described using this model, and therefore no simultaneous operations are 1997 possible. This model discusses only processor scheduling for runnable threads, but it should be 1998 noted that greatly enhanced predictability of realtime applications result if the sequencing of 1999 other resources takes processor scheduling policy into account. 2000 There is, conceptually, one thread list for each priority. Any runnable thread may be on any 2001 thread list. Multiple scheduling policies shall be provided. Each non-empty thread list is 2002 ordered, contains a head as one end of its order, and a tail as the other. The purpose of a 2003 scheduling policy is to define the allowable operations on this set of lists (for example, moving 2004 threads between and within lists). 2005 Each process shall be controlled by an associated scheduling policy and priority. These 2006 parameters may be specified by explicit application execution of the sched_setscheduler( ) or 2007 sched_setparam( ) functions. 546 Technical Standard (2000) (Draft July 31, 2000) General Information Realtime 2008 Each thread shall be controlled by an associated scheduling policy and priority. These 2009 parameters may be specified by explicit application execution of the pthread_setschedparam( ) 2010 function. 2011 Associated with each policy is a priority range. Each policy definition shall specify the minimum 2012 priority range for that policy. The priority ranges for each policy may but need not overlap the 2013 priority ranges of other policies. 2014 A conforming implementation shall select the thread that is defined as being at the head of the 2015 highest priority non-empty thread list to become a running thread, regardless of its associated 2016 policy. This thread is then removed from its thread list. 2017 Four scheduling policies are specifically required. Other implementation-defined scheduling | 2018 policies may be defined. The following symbols are defined in the Base Definitions volume of | 2019 IEEE Std. 1003.1-200x, : | 2020 SCHED_FIFO First in, first out (FIFO) scheduling policy. 2021 SCHED_RR Round robin scheduling policy. 2022 SS SCHED_SPORADIC Sporadic server scheduling policy. 2023 SCHED_OTHER Another scheduling policy. 2024 The values of these symbols shall be distinct. 2025 SCHED_FIFO 2026 Conforming implementations shall include a scheduling policy called the FIFO scheduling 2027 policy. 2028 Threads scheduled under this policy are chosen from a thread list that is ordered by the time its 2029 threads have been on the list without being executed; generally, the head of the list is the thread 2030 that has been on the list the longest time, and the tail is the thread that has been on the list the 2031 shortest time. 2032 Under the SCHED_FIFO policy, the modification of the definitional thread lists is as follows: 2033 1. When a running thread becomes a preempted thread, it becomes the head of the thread list 2034 for its priority. 2035 2. When a blocked thread becomes a runnable thread, it becomes the tail of the thread list for 2036 its priority. 2037 3. When a running thread calls the sched_setscheduler( ) function, the process specified in the 2038 function call is modified to the specified policy and the priority specified by the param 2039 argument. 2040 4. When a running thread calls the sched_setparam( ) function, the priority of the process 2041 specified in the function call is modified to the priority specified by the param argument. 2042 5. When a running thread calls the pthread_setschedparam( ) function, the thread specified in 2043 the function call is modified to the specified policy and the priority specified by the param 2044 argument. 2045 6. If a thread whose policy or priority has been modified is a running thread or is runnable, it 2046 then becomes the tail of the thread list for its new priority. 2047 7. When a running thread issues the sched_yield( ) function, the thread becomes the tail of the 2048 thread list for its priority. System Interfaces, Issue 6 547 Realtime General Information 2049 8. At no other time is the position of a thread with this scheduling policy within the thread 2050 lists affected. 2051 For this policy, valid priorities shall be within the range returned by the sched_get_priority_max( ) 2052 and sched_get_priority_min( ) functions when SCHED_FIFO is provided as the parameter. 2053 Conforming implementations shall provide a priority range of at least 32 priorities for this 2054 policy. 2055 SCHED_RR 2056 Conforming implementations shall include a scheduling policy called the round robin scheduling 2057 policy. This policy is identical to the SCHED_FIFO policy with the additional condition that 2058 when the implementation detects that a running thread has been executing as a running thread 2059 for a time period of the length returned by the sched_rr_get_interval( ) function or longer, the 2060 thread shall become the tail of its thread list and the head of that thread list shall be removed 2061 and made a running thread. 2062 The effect of this policy is to ensure that if there are multiple SCHED_RR threads at the same 2063 priority, one of them does not monopolize the processor. An application should not rely only on 2064 the use of SCHED_RR to ensure application progress among multiple threads if the application 2065 includes threads using the SCHED_FIFO policy at the same or higher priority levels or 2066 SCHED_RR threads at a higher priority level. 2067 A thread under this policy that is preempted and subsequently resumes execution as a running 2068 thread completes the unexpired portion of its round robin interval time period. 2069 For this policy, valid priorities shall be within the range returned by the sched_get_priority_max( ) 2070 and sched_get_priority_min( ) functions when SCHED_RR is provided as the parameter. 2071 Conforming implementations shall provide a priority range of at least 32 priorities for this 2072 policy. 2073 SCHED_SPORADIC 2074 SS|TSP The functionality described in this section is dependent on support of the Process Sporadic | 2075 Server or Thread Sporadic Server options (and the rest of this section is not further shaded for | 2076 these options). | 2077 If _POSIX_SPORADIC_SERVER or _POSIX_THREAD_SPORADIC_SERVER is defined, the | 2078 implementation shall include a scheduling policy identified by the value SCHED_SPORADIC. 2079 The sporadic server policy is based primarily on two parameters: the replenishment period and the 2080 available execution capacity. The replenishment period is given by the sched_ss_repl_period 2081 member of the sched_param structure. The available execution capacity is initialized to the 2082 value given by the sched_ss_init_budget member of the same parameter. The sporadic server 2083 policy is identical to the SCHED_FIFO policy with some additional conditions that cause the 2084 thread's assigned priority to be switched between the values specified by the sched_priority and 2085 sched_ss_low_priority members of the sched_param structure. 2086 The priority assigned to a thread using the sporadic server scheduling policy is determined in 2087 the following manner: if the available execution capacity is greater than zero and the number of 2088 pending replenishment operations is strictly less than sched_ss_max_repl, the thread is assigned 2089 the priority specified by sched_priority; otherwise, the assigned priority shall be 2090 sched_ss_low_priority. If the value of sched_priority is less than or equal to the value of 2091 sched_ss_low_priority, the results are undefined. When active, the thread shall belong to the 2092 thread list corresponding to its assigned priority level, according to the mentioned priority 2093 assignment. The modification of the available execution capacity and, consequently of the 2094 assigned priority, is done as follows: 548 Technical Standard (2000) (Draft July 31, 2000) General Information Realtime 2095 1. When the thread at the head of the sched_priority list becomes a running thread, its 2096 execution time shall be limited to at most its available execution capacity, plus the 2097 resolution of the execution time clock used for this scheduling policy. This resolution shall | 2098 be implementation-defined. | 2099 2. Each time the thread is inserted at the tail of the list associated with sched_priority- 2100 because as a blocked thread it became runnable with priority sched_priority or because a 2101 replenishment operation was performed-the time at which this operation is done is 2102 posted as the activation_time. 2103 3. When the running thread with assigned priority equal to sched_priority becomes a 2104 preempted thread, it becomes the head of the thread list for its priority, and the execution 2105 time consumed is subtracted from the available execution capacity. If the available 2106 execution capacity would become negative by this operation, it shall be set to zero. 2107 4. When the running thread with assigned priority equal to sched_priority becomes a blocked 2108 thread, the execution time consumed is subtracted from the available execution capacity, 2109 and a replenishment operation is scheduled, as described in 6 and 7. If the available | 2110 execution capacity would become negative by this operation, it shall be set to zero. | 2111 5. When the running thread with assigned priority equal to sched_priority reaches the limit 2112 imposed on its execution time, it becomes the tail of the thread list for 2113 sched_ss_low_priority, the execution time consumed is subtracted from the available 2114 execution capacity (which becomes zero), and a replenishment operation is scheduled, as | 2115 described in 6 and 7. | 2116 6. Each time a replenishment operation is scheduled, the amount of execution capacity to be 2117 replenished, replenish_amount, is set equal to the execution time consumed by the thread 2118 since the activation_time. The replenishment is scheduled to occur at activation_time plus 2119 sched_ss_repl_period. If the scheduled time obtained is before the current time, the | 2120 replenishment operation is carried out immediately. Several replenishment operations may | 2121 be pending at the same time, each of which will be serviced at its respective scheduled | 2122 time. With the above rules, the number of replenishment operations simultaneously | 2123 pending for a given thread that is scheduled under the sporadic server policy shall not be | 2124 greater than sched_ss_max_repl. | 2125 7. A replenishment operation consists of adding the corresponding replenish_amount to the | 2126 available execution capacity at the scheduled time. If, as a consequence of this operation, | 2127 the execution capacity would become larger than sched_ss_initial_budget, it shall be | 2128 rounded down to a value equal to sched_ss_initial_budget. Additionally, if the thread was | 2129 runnable or running, and had assigned priority equal to sched_ss_low_priority, then it | 2130 becomes the tail of the thread list for sched_priority. 2131 Execution time is defined in Section 2.2.2 (on page 513). 2132 For this policy, changing the value of a CPU-time clock via clock_settime( ) shall have no effect on 2133 its behavior. 2134 For this policy, valid priorities shall be within the range returned by the sched_get_priority_min( ) 2135 and sched_get_priority_max( ) functions when SCHED_SPORADIC is provided as the parameter. 2136 Conforming implementations shall provide a priority range of at least 32 distinct priorities for 2137 this policy. | System Interfaces, Issue 6 549 Realtime General Information 2138 SCHED_OTHER 2139 Conforming implementations shall include one scheduling policy identified as SCHED_OTHER 2140 (which may execute identically with either the FIFO or round robin scheduling policy). The 2141 effect of scheduling threads with the SCHED_OTHER policy in a system in which other threads 2142 SS are executing under SCHED_FIFO, SCHED_RR, or SCHED_SPORADIC is implementation- | 2143 defined. | 2144 This policy is defined to allow conforming applications to be able to indicate that they no longer 2145 need a realtime scheduling policy in a portable manner. 2146 For threads executing under this policy, the implementation shall use only priorities within the 2147 range returned by the sched_get_priority_max( ) and sched_get_priority_min( ) functions when 2148 SCHED_OTHER is provided as the parameter. 2149 2.8.5 Clocks and Timers 2150 TMR The functionality described in this section is dependent on support of the Timers option (and the | 2151 rest of this section is not further shaded for this option). | 2152 The header defines the types and manifest constants used by the timing facility. 2153 Time Value Specification Structures 2154 Many of the timing facility functions accept or return time value specifications. A time value 2155 structure timespec specifies a single time value and includes at least the following members: 2156 _______________________________________________ 2157 _ Member Type Member Name Description ______________________________________________ 2158 time_t tv_sec Seconds. 2159 _ long tv_nsec Nanoseconds. ______________________________________________ 2160 The tv_nsec member is only valid if greater than or equal to zero, and less than the number of 2161 nanoseconds in a second (1,000 million). The time interval described by this structure is (tv_sec * 2162 109 + tv_nsec) nanoseconds. 2163 A time value structure itimerspec specifies an initial timer value and a repetition interval for use 2164 by the per-process timer functions. This structure includes at least the following members: 2165 ___________________________________________________ 2166 _ Member Type Member Name Description __________________________________________________ 2167 struct timespec it_interval Timer period. 2168 _ struct timespec it_value Timer expiration. __________________________________________________ 2169 If the value described by it_value is non-zero, it indicates the time to or time of the next timer 2170 expiration (for relative and absolute timer values, respectively). If the value described by it_value 2171 is zero, the timer shall be disarmed. 2172 If the value described by it_interval is non-zero, it specifies an interval to be used in reloading the 2173 timer when it expires; that is, a periodic timer is specified. If the value described by it_interval is 2174 zero, the timer is disarmed after its next expiration; that is, a one-shot timer is specified. 550 Technical Standard (2000) (Draft July 31, 2000) General Information Realtime 2175 Timer Event Notification Control Block 2176 RTS Per-process timers may be created that notify the process of timer expirations by queuing a 2177 realtime extended signal. The sigevent structure, defined in the Base Definitions volume of | 2178 IEEE Std. 1003.1-200x, , is used in creating such a timer. The sigevent structure | 2179 contains the signal number and an application-specific data value to be used when notifying the 2180 calling process of timer expiration events. 2181 Manifest Constants 2182 The following constants are defined in the Base Definitions volume of IEEE Std. 1003.1-200x, | 2183 : 2184 CLOCK_REALTIME The identifier for the system-wide realtime clock. 2185 TIMER_ABSTIME Flag indicating time is absolute with respect to the clock associated 2186 with a timer. 2187 MON CLOCK_MONOTONIC The identifier for the system-wide monotonic clock, which is defined 2188 as a clock whose value cannot be set via clock_settime( ) and which 2189 cannot have backward clock jumps. The maximum possible clock | 2190 jump is implementation-defined. | 2191 MON The maximum allowable resolution for the CLOCK_REALTIME and the 2192 CLOCK_MONOTONIC clocks and all time services based on these clocks is represented by 2193 {_POSIX_CLOCKRES_MIN} and is defined as 20ms (1/50 of a second). Implementations may 2194 support smaller values of resolution for these clocks to provide finer granularity time bases. The 2195 actual resolution supported by an implementation for a specific clock is obtained using the 2196 clock_getres( ) function. If the actual resolution supported for a time service based on one of these 2197 clocks differs from the resolution supported for that clock, the implementation shall document 2198 this difference. 2199 MON The minimum allowable maximum value for the CLOCK_REALTIME and the 2200 CLOCK_MONOTONIC clocks and all absolute time services based on them is the same as that 2201 defined by the ISO C standard for the time_t type. If the maximum value supported by a time 2202 service based on one of these clocks differs from the maximum value supported by that clock, 2203 the implementation shall document this difference. 2204 Execution Time Monitoring 2205 CPT If _POSIX_CPUTIME is defined, process CPU-time clocks shall be supported in addition to the 2206 clocks described in Manifest Constants. 2207 TCT If _POSIX_THREAD_CPUTIME is defined, thread CPU-time clocks shall be supported. 2208 CPT|TCT CPU-time clocks measure execution or CPU time, which is defined in the Base Definitions | 2209 volume of IEEE Std. 1003.1-200x, Section 3.120, CPU Time (Execution Time). The mechanism | 2210 used to measure execution time is described in the Base Definitions volume of | 2211 IEEE Std. 1003.1-200x, Section 4.7, Measurement of Execution Time. | 2212 CPT If _POSIX_CPUTIME is defined, the following constant of the type clockid_t shall be defined in 2213 : 2214 CLOCK_PROCESS_CPUTIME_ID 2215 When this value of the type clockid_t is used in a clock( ) or timer*( ) function call, it is 2216 interpreted as the identifier of the CPU-time clock associated with the process making the 2217 function call. 2218 System Interfaces, Issue 6 551 Realtime General Information 2219 TCT If _POSIX_THREAD_CPUTIME is defined, the following constant of the type clockid_t shall be 2220 defined in : 2221 CLOCK_THREAD_CPUTIME_ID 2222 When this value of the type clockid_t is used in a clock( ) or timer*( ) function call, it is 2223 interpreted as the identifier of the CPU-time clock associated with the thread making the 2224 function call. 2225 552 Technical Standard (2000) (Draft July 31, 2000) General Information Threads 2226 2.9 Threads 2227 THR The functionality described in this section is dependent on support of the Threads option (and | 2228 the rest of this section is not further shaded for this option). | 2229 This section defines functionality to support multiple flows of control, called threads, within a | 2230 process. For the definition of threads, see the Base Definitions volume of IEEE Std. 1003.1-200x, | 2231 Section 3.395, Thread. | 2232 The specific functional areas covered by threads and their scope includes: | 2233 * Thread management: the creation, control, and termination of multiple flows of control in the 2234 same process under the assumption of a common shared address space 2235 * Synchronization primitives optimized for tightly coupled operation of multiple control flows 2236 in a common, shared address space | 2237 2.9.1 Thread-Safety 2238 All functions defined by this volume of IEEE Std. 1003.1-200x shall be thread-safe, except that 2239 the following functions need not be thread-safe. 2240 asctime( ) gethostbyname( ) getprotobynumber( ) inet_ntoa( ) ttyname( ) 2241 ctime( ) gethostent( ) getprotoent( ) localtime( ) unsetenv( ) 2242 getc_unlocked( ) getlogin( ) getpwnam( ) putc_unlocked( ) wcstombs( ) 2243 getchar_unlocked( ) getnetbyaddr( ) getpwuid( ) putchar_unlocked( ) wctomb( ) 2244 getenv( ) getnetbyname( ) getservbyname( ) rand( ) 2245 getgrgid( ) getnetent( ) getservbyport( ) readdir( ) 2246 getgrnam( ) getopt( ) getservent( ) setenv( ) 2247 gethostbyaddr( ) getprotobyname( ) gmtime( ) strtok( ) 2248 XSI basename( ) dbm_open( ) fcvt( ) hdestroy( ) setgrent( ) 2249 catgets( ) dbm_store( ) gcvt( ) hsearch( ) setkey( ) 2250 crypt( ) dirname( ) getdate( ) l64a( ) setpwent( ) 2251 dbm_clearerr( ) dlerror( ) getenv( ) lgamma( ) setutxent( ) 2252 dbm_close( ) drand48( ) getgrent( ) lrand48( ) strerror( ) 2253 dbm_delete( ) ecvt( ) getpwent( ) mrand48( ) 2254 dbm_error( ) encrypt( ) getutxent( ) nl_langinfo ( ) 2255 dbm_fetch( ) endgrent( ) getutxid( ) ptsname( ) 2256 dbm_firstkey( ) endpwent( ) getutxline( ) putenv( ) 2257 dbm_nextkey( ) endutxent( ) hcreate( ) pututxline( ) 2258 2259 The read( ) function need not be thread-safe when reading from a pipe, FIFO, socket, or terminal | 2260 device. | 2261 Note: While a read from a pipe of {PIPE_MAX}*2 bytes may not generate a single atomic | 2262 and thread-safe stream of bytes, it should generate ``several'' (individually atomic) | 2263 thread-safe streams of bytes. Similiarly, while reading from a terminal device may | 2264 not generate a single atomic and thread-safe stream of bytes, it should generate some | 2265 finite number of (individually atomic) and thread-safe streams of bytes. That is, | 2266 concurrent calls to read for a pipe, FIFO, or terminal device are not allowed to result | 2267 in corrupting the stream of bytes or other internal data. However, read( ), in these | 2268 cases, is not required to return a single contiguous and atomic stream of bytes. | System Interfaces, Issue 6 553 Threads General Information 2269 The ctermid( ) and tmpnam( ) functions need not be thread-safe if passed a NULL argument. The | 2270 wcrtomb( ) and wcsrtombs( ) functions need not be thread-safe if passed a NULL ps argument. 2271 Implementations shall provide internal synchronization as necessary in order to satisfy this 2272 requirement. 2273 2.9.2 Thread IDs 2274 Although implementations may have thread IDs that are unique in a system, applications 2275 should only assume that thread IDs are usable and unique within a single process. The effect of 2276 calling any of the functions defined in this volume of IEEE Std. 1003.1-200x and passing as an 2277 argument the thread ID of a thread from another process is unspecified. A conforming 2278 implementation is free to reuse a thread ID after the thread terminates if it was created with the 2279 detachstate attribute set to PTHREAD_CREATE_DETACHED or if pthread_detach( ) or 2280 pthread_join( ) has been called for that thread. If a thread is detached, its thread ID is invalid for 2281 use as an argument in a call to pthread_detach( ) or pthread_join( ). | 2282 2.9.3 Thread Mutexes 2283 A thread that has blocked shall not prevent any unblocked thread that is eligible to use the same 2284 processing resources from eventually making forward progress in its execution. Eligibility for 2285 processing resources is determined by the scheduling policy. 2286 A thread becomes the owner of a mutex, m, when one of the following occurs: 2287 * It returns successfully from pthread_mutex_lock( ) with m as the mutex argument. 2288 * It returns successfully from pthread_mutex_trylock( ) with m as the mutex argument. 2289 TMO * It returns successfully from pthread_mutex_timedwait( ) with m as the mutex argument. | 2290 * It returns (successfully or not) from pthread_cond_wait( ) with m as the mutex argument | 2291 (except as explicitly indicated otherwise for certain errors). 2292 * It returns (successfully or not) from pthread_cond_timedwait( ) with m as the mutex argument 2293 (except as explicitly indicated otherwise for certain errors). 2294 The thread remains the owner of m until one of the following occurs: 2295 * It executes pthread_mutex_unlock( ) with m as the mutex argument 2296 * It blocks in a call to pthread_cond_wait( ) with m as the mutex argument. 2297 * It blocks in a call to pthread_cond_timedwait( ) with m as the mutex argument. 2298 The implementation behaves as if at all times there is at most one owner of any mutex. 2299 A thread that becomes the owner of a mutex is said to have acquired the mutex and the mutex is 2300 said to have become locked; when a thread gives up ownership of a mutex it is said to have 2301 released the mutex and the mutex is said to have become unlocked. | 554 Technical Standard (2000) (Draft July 31, 2000) General Information Threads 2302 2.9.4 Thread Scheduling 2303 Thread Scheduling Attributes 2304 Thread scheduling attributes are dependent on support of the Thread Execution Scheduling 2305 option. 2306 In support of the scheduling function, threads have attributes which are accessed through the 2307 pthread_attr_t thread creation attributes object. 2308 The contentionscope attribute defines the scheduling contention scope of the thread to be either 2309 PTHREAD_SCOPE_PROCESS or PTHREAD_SCOPE_SYSTEM. 2310 The inheritsched attribute specifies whether a newly created thread is to inherit the scheduling 2311 attributes of the creating thread or to have its scheduling values set according to the other 2312 scheduling attributes in the pthread_attr_t object. 2313 The schedpolicy attribute defines the scheduling policy for the thread. The schedparam attribute 2314 defines the scheduling parameters for the thread. The interaction of threads having different 2315 policies within a process is described as part of the definition of those policies. 2316 If the Thread Execution Scheduling option is defined, and the schedpolicy attribute specifies one | 2317 of the priority-based policies defined under this option, the schedparam attribute contains the 2318 scheduling priority of the thread. A conforming implementation ensures that the priority value 2319 in schedparam is in the range associated with the scheduling policy when the thread attributes 2320 object is used to create a thread, or when the scheduling attributes of a thread are dynamically 2321 modified. The meaning of the priority value in schedparam is the same as that of priority. 2322 TSP If _POSIX_THREAD_SPORADIC_SERVER is defined, the schedparam attribute supports four 2323 new members that are used for the sporadic server scheduling policy. These members are 2324 sched_ss_low_priority, sched_ss_repl_period, sched_ss_init_budget, and sched_ss_max_repl. The 2325 meaning of these attributes is the same as in the definitions that appear under Section 2.8.4 (on 2326 page 546). 2327 When a process is created, its single thread has a scheduling policy and associated attributes 2328 equal to the process' policy and attributes. The default scheduling contention scope value is | 2329 implementation-defined. The default values of other scheduling attributes are implementation- | 2330 defined. | 2331 Thread Scheduling Contention Scope 2332 The scheduling contention scope of a thread defines the set of threads with which the thread 2333 competes for use of the processing resources. The scheduling operation selects at most one 2334 thread to execute on each processor at any point in time and the thread's scheduling attributes 2335 (for example, priority), whether under process scheduling contention scope or system scheduling 2336 contention scope, are the parameters used to determine the scheduling decision. 2337 The scheduling contention scope, in the context of scheduling a mixed scope environment, 2338 effects threads as follows: 2339 * A thread created with PTHREAD_SCOPE_SYSTEM scheduling contention scope contends 2340 for resources with all other threads in the same scheduling allocation domain relative to their 2341 system scheduling attributes. The system scheduling attributes of a thread created with 2342 PTHREAD_SCOPE_SYSTEM scheduling contention scope are the scheduling attributes with 2343 which the thread was created. The system scheduling attributes of a thread created with 2344 PTHREAD_SCOPE_PROCESS scheduling contention scope are the implementation-defined | 2345 mapping into system attribute space of the scheduling attributes with which the thread was | System Interfaces, Issue 6 555 Threads General Information 2346 created. 2347 * Threads created with PTHREAD_SCOPE_PROCESS scheduling contention scope contend 2348 directly with other threads within their process that were created with 2349 PTHREAD_SCOPE_PROCESS scheduling contention scope. The contention is resolved 2350 based on the threads' scheduling attributes and policies. It is unspecified how such threads 2351 are scheduled relative to threads in other processes or threads with 2352 PTHREAD_SCOPE_SYSTEM scheduling contention scope. 2353 * Conforming implementations shall support the PTHREAD_SCOPE_PROCESS scheduling 2354 contention scope, the PTHREAD_SCOPE_SYSTEM scheduling contention scope, or both. 2355 Scheduling Allocation Domain 2356 Implementations shall support scheduling allocation domains containing one or more 2357 processors. It should be noted that the presence of multiple processors does not automatically 2358 indicate a scheduling allocation domain size greater than one. Conforming implementations on 2359 multiprocessors may map all or any subset of the CPUs to one or multiple scheduling allocation 2360 domains, and could define these scheduling allocation domains on a per-thread, per-process, or 2361 per-system basis, depending on the types of applications intended to be supported by the 2362 implementation. The scheduling allocation domain is independent of scheduling contention 2363 scope, as the scheduling contention scope merely defines the set of threads with which a thread 2364 contends for processor resources, while scheduling allocation domain defines the set of 2365 processors for which it contends. The semantics of how this contention is resolved among 2366 threads for processors is determined by the scheduling policies of the threads. 2367 The choice of scheduling allocation domain size and the level of application control over 2368 scheduling allocation domains is implementation-defined. Conforming implementations may | 2369 change the size of scheduling allocation domains and the binding of threads to scheduling | 2370 allocation domains at any time. 2371 For application threads with scheduling allocation domains of size equal to one, the scheduling 2372 rules defined for SCHED_FIFO and SCHED_RR shall be used; see Scheduling Policies (on page 2373 546). All threads with system scheduling contention scope, regardless of the processes in which 2374 they reside, compete for the processor according to their priorities. Threads with process 2375 scheduling contention scope compete only with other threads with process scheduling 2376 contention scope within their process. 2377 For application threads with scheduling allocation domains of size greater than one, the rules 2378 TSP defined for SCHED_FIFO, SCHED_RR, and SCHED_SPORADIC shall be used in an | 2379 implementation-defined manner. Each thread with system scheduling contention scope | 2380 competes for the processors in its scheduling allocation domain in an implementation-defined | 2381 manner according to its priority. Threads with process scheduling contention scope are | 2382 scheduled relative to other threads within the same scheduling contention scope in the process. 2383 TSP If _POSIX_THREAD_SPORADIC_SERVER is defined, the rules defined for SCHED_SPORADIC 2384 in Scheduling Policies (on page 546) shall be used in an implementation-defined manner for | 2385 application threads whose scheduling allocation domain size is greater than one. | 556 Technical Standard (2000) (Draft July 31, 2000) General Information Threads 2386 Scheduling Documentation 2387 If _POSIX_PRIORITY_SCHEDULING is defined, then any scheduling policies beyond 2388 TSP SCHED_OTHER, SCHED_FIFO, SCHED_RR, and SCHED_SPORADIC, as well as the effects of 2389 the scheduling policies indicated by these other values, and the attributes required in order to 2390 support such a policy, are implementation-defined. Furthermore, the implementation shall | 2391 document the effect of all processor scheduling allocation domain values supported for these 2392 policies. 2393 2.9.5 Thread Cancelation 2394 The thread cancelation mechanism allows a thread to terminate the execution of any other 2395 thread in the process in a controlled manner. The target thread (that is, the one that is being 2396 canceled) is allowed to hold cancelation requests pending in a number of ways and to perform 2397 application-specific cleanup processing when the notice of cancelation is acted upon. 2398 Cancelation is controlled by the cancelation control functions. Each thread maintains its own 2399 cancelability state. Cancelation may only occur at cancelation points or when the thread is 2400 asynchronously cancelable. 2401 The thread cancelation mechanism described in this section depends upon programs having set 2402 deferred cancelability state, which is specified as the default. Applications shall also carefully 2403 follow static lexical scoping rules in their execution behavior. For example, use of setjmp( ), 2404 return, goto, and so on, to leave user-defined cancelation scopes without doing the necessary 2405 scope pop operation results in undefined behavior. 2406 Use of asynchronous cancelability while holding resources which potentially need to be released 2407 may result in resource loss. Similarly, cancelation scopes may only be safely manipulated 2408 (pushed and popped) when the thread is in the deferred or disabled cancelability states. 2409 2.9.5.1 Cancelability States 2410 The cancelability state of a thread determines the action taken upon receipt of a cancelation 2411 request. The thread may control cancelation in a number of ways. 2412 Each thread maintains its own cancelability state, which may be encoded in two bits: 2413 1. Cancelability-Enable: When cancelability is PTHREAD_CANCEL_DISABLE (as defined in | 2414 the Base Definitions volume of IEEE Std. 1003.1-200x, ), cancelation requests | 2415 against the target thread are held pending. By default, cancelability is set to 2416 PTHREAD_CANCEL_ENABLE (as defined in ). 2417 2. Cancelability Type: When cancelability is enabled and the cancelability type is 2418 PTHREAD_CANCEL_ASYNCHRONOUS (as defined in ), new or pending 2419 cancelation requests may be acted upon at any time. When cancelability is enabled and the 2420 cancelability type is PTHREAD_CANCEL_DEFERRED (as defined in ), 2421 cancelation requests are held pending until a cancelation point (see below) is reached. If 2422 cancelability is disabled, the setting of the cancelability type has no immediate effect as all 2423 cancelation requests are held pending; however, once cancelability is enabled again the 2424 new type is in effect. The cancelability type is PTHREAD_CANCEL_DEFERRED in all 2425 newly created threads including the thread in which main( ) was first invoked. System Interfaces, Issue 6 557 Threads General Information 2426 2.9.5.2 Cancelation Points 2427 Cancelation points occur when a thread is executing the following functions: 2428 accept( ) mq_timedsend( ) putpmsg( ) sigsuspend( ) 2429 aio_suspend( ) msgrcv( ) pwrite( ) sigtimedwait( ) 2430 clock_nanosleep( ) msgsnd( ) read( ) sigwait( ) 2431 close( ) msync( ) readv( ) sigwaitinfo ( ) 2432 connect( ) nanosleep( ) recv( ) sleep( ) 2433 creat( ) open( ) recvfrom( ) system( ) 2434 fcntl( )1 pause( ) recvmsg( ) tcdrain( ) 2435 fsync( ) poll( ) select( ) usleep( ) 2436 getmsg( ) pread( ) sem_timedwait( ) wait( ) 2437 getpmsg( ) pthread_cond_timedwait( ) sem_wait( ) waitid( ) 2438 lockf( ) pthread_cond_wait( ) send( ) waitpid( ) 2439 mq_receive( ) pthread_join( ) sendmsg( ) write( ) 2440 mq_send( ) pthread_testcancel( ) sendto( ) writev( ) 2441 mq_timedreceive( ) putmsg( ) sigpause( ) 2442 __________________ 2443 1. When the cmd argument is F_SETLKW. 558 Technical Standard (2000) (Draft July 31, 2000) General Information Threads 2444 A cancelation point may also occur when a thread is executing the following functions: 2445 catclose( ) ftell( ) getwc( ) pthread_rwlock_wrlock( ) 2446 catgets( ) ftello( ) getwchar( ) putc( ) 2447 catopen( ) ftw( ) getwd( ) putc_unlocked( ) 2448 closedir( ) fwprintf( ) glob( ) putchar( ) 2449 closelog( ) fwrite( ) iconv_close( ) putchar_unlocked( ) 2450 ctermid( ) fwscanf( ) iconv_open( ) puts( ) 2451 dbm_close( ) getc( ) ioctl( ) pututxline( ) 2452 dbm_delete( ) getc_unlocked( ) lseek( ) putwc( ) 2453 dbm_fetch( ) getchar( ) mkstemp( ) putwchar( ) 2454 dbm_nextkey( ) getchar_unlocked( ) nftw( ) readdir( ) 2455 dbm_open( ) getcwd( ) opendir( ) readdir_r( ) 2456 dbm_store( ) getdate( ) openlog( ) remove( ) 2457 dlclose( ) getgrent( ) pclose( ) rename( ) 2458 dlopen( ) getgrgid( ) perror( ) rewind( ) 2459 endgrent( ) getgrgid_r( ) popen( ) rewinddir( ) 2460 endhostent( ) getgrnam( ) posix_fadvise ( ) scanf( ) 2461 endnetent( ) getgrnam_r( ) posix_fallocate( ) seekdir( ) 2462 endprotoent( ) gethostbyaddr( ) posix_madvise( ) semop( ) 2463 endpwent( ) gethostbyname( ) posix_spawn( ) setgrent( ) 2464 endservent( ) gethostent( ) posix_spawnp( ) sethostent( ) 2465 endutxent( ) gethostname( ) posix_trace_clear( ) setnetent( ) 2466 fclose( ) getlogin( ) posix_trace_close( ) setprotoent( ) 2467 fcntl( )2 getlogin_r( ) posix_trace_create( ) setpwent( ) 2468 fflush( ) getnetbyaddr( ) posix_trace_create_withlog( ) setservent( ) 2469 fgetc( ) getnetbyname( ) posix_trace_eventtypelist_getnext_id( ) setutxent( ) 2470 fgetpos( ) getnetent( ) posix_trace_eventtypelist_rewind( ) strerror( ) 2471 fgets( ) getprotobyname( ) posix_trace_flush( ) syslog( ) 2472 fgetwc( ) getprotobynumber( ) posix_trace_get_attr( ) tmpfile( ) 2473 fgetws( ) getprotoent( ) posix_trace_get_filter( ) tmpnam( ) 2474 fopen( ) getpwent( ) posix_trace_get_status( ) ttyname( ) 2475 fprintf( ) getpwnam( ) posix_trace_getnext_event( ) ttyname_r( ) 2476 fputc( ) getpwnam_r( ) posix_trace_open( ) ungetc( ) 2477 fputs( ) getpwuid( ) posix_trace_rewind( ) ungetwc( ) 2478 fputwc( ) getpwuid_r( ) posix_trace_set_filter( ) unlink( ) 2479 fputws( ) gets( ) posix_trace_shutdown( ) vfprintf( ) 2480 fread( ) getservbyname( ) posix_trace_timedgetnext_event( ) vfwprintf( ) 2481 freopen( ) getservbyport( ) posix_typed_mem_open( ) vprintf( ) 2482 fscanf( ) getservent( ) printf( ) vwprintf( ) 2483 fseek( ) getutxent( ) pthread_rwlock_rdlock( ) wprintf( ) 2484 fseeko( ) getutxid( ) pthread_rwlock_timedrdlock( ) wscanf( ) 2485 fsetpos( ) getutxline( ) pthread_rwlock_timedwrlock( ) 2486 An implementation shall not introduce cancelation points into any other functions specified in 2487 this volume of IEEE Std. 1003.1-200x. 2488 __________________ 2489 2. For any value of the cmd argument. System Interfaces, Issue 6 559 Threads General Information 2490 The side effects of acting upon a cancelation request while suspended during a call of a function 2491 are the same as the side effects that may be seen in a single-threaded program when a call to a 2492 function is interrupted by a signal and the given function returns [EINTR]. Any such side effects 2493 occur before any cancelation cleanup handlers are called. 2494 Whenever a thread has cancelability enabled and a cancelation request has been made with that 2495 thread as the target and the thread calls pthread_testcancel( ), then the cancelation request is acted 2496 upon before pthread_testcancel( ) returns. If a thread has cancelability enabled and the thread has 2497 a cancelation request pending and the thread is suspended at a cancelation point waiting for an 2498 event to occur, then the cancelation request shall be acted upon. However, if the thread is 2499 suspended at a cancelation point and the event that it is waiting for occurs before the cancelation 2500 request is acted upon, it is unspecified whether the cancelation request is acted upon or whether 2501 the request remains pending and the thread resumes normal execution. 2502 2.9.5.3 Thread Cancelation Cleanup Handlers 2503 Each thread maintains a list of cancelation cleanup handlers. The programmer uses the 2504 pthread_cleanup_push( ) and pthread_cleanup_pop( ) functions to place routines on and remove 2505 routines from this list. 2506 When a cancelation request is acted upon, the routines in the list are invoked one by one in LIFO 2507 sequence; that is, the last routine pushed onto the list (Last In) is the first to be invoked (First 2508 Out). The thread invokes the cancelation cleanup handler with cancelation disabled until the last 2509 cancelation cleanup handler returns. When the cancelation cleanup handler for a scope is 2510 invoked, the storage for that scope remains valid. If the last cancelation cleanup handler returns, 2511 thread execution is terminated and a status of PTHREAD_CANCELED is made available to any 2512 threads joining with the target. The symbolic constant PTHREAD_CANCELED expands to a 2513 constant expression of type (void*) whose value matches no pointer to an object in memory nor 2514 the value NULL. 2515 The cancelation cleanup handlers are also invoked when the thread calls pthread_exit( ). 2516 A side effect of acting upon a cancelation request while in a condition variable wait is that the 2517 mutex is re-acquired before calling the first cancelation cleanup handler. In addition, the thread 2518 is no longer considered to be waiting for the condition and the thread shall not have consumed 2519 any pending condition signals on the condition. 2520 A cancelation cleanup handler cannot exit via longjmp( ) or siglongjmp( ). 2521 2.9.5.4 Async-Cancel Safety 2522 The pthread_cancel( ), pthread_setcancelstate( ), and pthread_setcanceltype( ) functions are defined to 2523 be async-cancel safe. 2524 No other functions in this volume of IEEE Std. 1003.1-200x are required to be async-cancel-safe. 2525 2.9.6 Thread Read-Write Locks 2526 Multiple readers, single writer (read-write) locks allow many threads to have simultaneous | 2527 read-only access to data while allowing only one thread to have exclusive write access at any 2528 given time. They are typically used to protect data that is read-only more frequently than it is 2529 changed. 2530 One or more readers acquire read access to the resource by performing a read lock operation on 2531 the associated read-write lock. A writer acquires exclusive write access by performing a write 2532 lock operation. Basically, all readers exclude any writers and a writer excludes all readers and 2533 any other writers. 560 Technical Standard (2000) (Draft July 31, 2000) General Information Threads 2534 A thread that has blocked on a read-write lock (for example, has not yet returned from a 2535 pthread_rwlock_rdlock( ) or pthread_rwlock_wrlock( ) call) shall not prevent any unblocked thread 2536 that is eligible to use the same processing resources from eventually making forward progress in 2537 its execution. Eligibility for processing resources shall be determined by the scheduling policy. 2538 Read-write locks can be used to synchronize threads in the current process and other processes if 2539 they are allocated in memory that is writable and shared among the cooperating processes and 2540 have been initialized for this behavior. | 2541 2.9.7 Thread Interactions with Regular File Operations 2542 All of the functions chmod( ), close( ), fchmod( ), fcntl( ), fstat( ), ftruncate( ), lseek( ), open( ), read( ), 2543 readlink( ), stat( ), symlink( ), and write( ) shall be atomic with respect to each other in the effects 2544 specified in IEEE Std. 1003.1-200x when they operate on regular files. If two threads each call one 2545 of these functions, each call shall either see all of the specified effects of the other call, or none of 2546 them. System Interfaces, Issue 6 561 Sockets General Information 2547 2.10 Sockets 2548 A socket is an endpoint for communication using the facilities described in this section. A socket 2549 is created with a specific socket type, described in Section 2.10.6 (on page 563), and is associated 2550 with a specific protocol, detailed in Section 2.10.2. A socket is accessed via a file descriptor 2551 obtained when the socket is created. 2552 2.10.1 Protocol Families 2553 All network protocols are associated with a specific protocol family. A protocol family provides 2554 basic services to the protocol implementation to allow it to function within a specific network 2555 environment. These services may include packet fragmentation and reassembly, routing, 2556 addressing, and basic transport. A protocol family may support multiple methods of addressing. 2557 Each method represents an address family. A protocol family is normally comprised of a 2558 number of protocols, one per socket type. Each protocol is characterized by an abstract socket 2559 type. It is not required that a protocol family support all socket types. A protocol family may 2560 contain multiple protocols supporting the same socket abstraction. 2561 Section 2.10.17 (on page 569), Section 2.10.18 (on page 569), and Section 2.10.19 (on page 570), 2562 respectively, describe the use of sockets for local UNIX connections, for Internet protocols based 2563 on IPv4, and for Internet protocols based on IPv6. 2564 2.10.2 Protocols 2565 A protocol supports one of the socket abstractions detailed in Section 2.10.6 (on page 563). | 2566 Selecting a protocol involves specifying the protocol family, socket type, and protocol number to | 2567 the socket( ) function. Protocols normally accept only one type of address format, usually | 2568 determined by the addressing structure inherent in the design of the protocol family/network | 2569 architecture. Certain semantics of the basic socket abstractions are protocol-specific. All | 2570 protocols are expected to support the basic model for their particular socket type, but may, in | 2571 addition, provide non-standard facilities or extensions to a mechanism. | 2572 2.10.3 Addressing 2573 Associated with each protocol family is at least one address family. An address family defines 2574 the format of a socket address. All network addresses are described using a general structure, 2575 called a sockaddr, as defined in the Base Definitions volume of IEEE Std. 1003.1-200x, | 2576 . However, each address family imposes finer and more specific structure, 2577 generally defining a structure with fields specific to the address family. The field sa_family in the 2578 sockaddr structure contains the address family identifier, specifying the format of the sa_data 2579 area. The size of the sa_data area is unspecified. 2580 2.10.4 Routing 2581 Sockets provides packet routing facilities. A routing information database is maintained, which 2582 is used in selecting the appropriate network interface when transmitting packets. 562 Technical Standard (2000) (Draft July 31, 2000) General Information Sockets 2583 2.10.5 Interfaces 2584 Each network interface in a system corresponds to a path through which messages can be sent 2585 and received. A network interface usually has a hardware device associated with it, though 2586 certain interfaces such as the loopback interface, do not. 2587 2.10.6 Socket Types 2588 A socket is created with a specific type, which defines the communication semantics and which 2589 allows the selection of an appropriate communication protocol. Three types are defined: 2590 SOCK_STREAM, SOCK_SEQPACKET, and SOCK_DGRAM. Implementations may specify 2591 additional socket types. 2592 The SOCK_STREAM socket type provides reliable, sequenced, full-duplex octet streams 2593 between the socket and a peer to which the socket is connected. A socket of type 2594 SOCK_STREAM must be in a connected state before any data may be sent or received. Record 2595 boundaries are not maintained; data sent on a stream socket using output operations of one size 2596 may be received using input operations of smaller or larger sizes without loss of data. Data may 2597 be buffered; successful return from an output function does not imply that the data has been 2598 delivered to the peer or even transmitted from the local system. If data cannot be successfully 2599 transmitted within a given time then the connection is considered broken, and subsequent 2600 operations shall fail. A SIGPIPE signal is raised if a thread sends on a broken stream (one that is | 2601 no longer connected). Support for an out-of-band data transmission facility is protocol-specific. | 2602 The SOCK_SEQPACKET socket type is similar to the SOCK_STREAM type, and is also 2603 connection-oriented. The only difference between these types is that record boundaries are 2604 maintained using the SOCK_SEQPACKET type. A record can be sent using one or more output 2605 operations and received using one or more input operations, but a single operation never 2606 transfers parts of more than one record. Record boundaries are visible to the receiver via the 2607 MSG_EOR flag in the received message flags returned by the recvmsg( ) function. It is protocol- 2608 specific whether a maximum record size is imposed. 2609 The SOCK_DGRAM socket type supports connectionless data transfer which is not necessarily 2610 acknowledged or reliable. Datagrams may be sent to a peer named in each output operation, and 2611 incoming datagrams may be received from multiple sources. The source address of each 2612 datagram is available when receiving the datagram. An application may also pre-specify a peer 2613 address, in which case calls to output functions shall send to the pre-specified peer. If a peer has 2614 been specified, only datagrams from that peer shall be received. A datagram must be sent in a 2615 single output operation, and must be received in a single input operation. The maximum size of 2616 a datagram is protocol-specific; with some protocols, the limit is implementation-defined. | 2617 Output datagrams may be buffered within the system; thus, a successful return from an output | 2618 function does not guarantee that a datagram is actually sent or received. However, 2619 implementations should attempt to detect any errors possible before the return of an output 2620 function, reporting any error by an unsuccessful return value. 2621 2.10.7 Socket I/O Mode 2622 The I/O mode of a socket is described by the O_NONBLOCK file status flag which pertains to | 2623 the open file description for the socket. This flag is initially off when a socket is created, but may | 2624 be set and cleared by the use of the F_SETFL command of the fcntl( ) function. | 2625 When the O_NONBLOCK flag is set, functions that would normally block until they are 2626 complete either return immediately with an error, or they complete asynchronously to the 2627 execution of the calling process. Data transfer operations (the read( ), write( ), send( ), and recv( ) | 2628 functions) complete immediately, transfer only as much as is available, and then return without | 2629 blocking, or return an error indicating that no transfer could be made without blocking. The | System Interfaces, Issue 6 563 Sockets General Information 2630 connect( ) function initiates a connection and returns without blocking when O_NONBLOCK is 2631 set; it returns the error [EINPROGRESS] to indicate that the connection was initiated 2632 successfully, but that it has not yet completed. | 2633 2.10.8 Socket Owner 2634 The owner of a socket is unset when a socket is created. The owner may be set to a process ID or 2635 process group ID using the F_SETOWN command of the fcntl( ) function. 2636 2.10.9 Socket Queue Limits 2637 The transmit and receive queue sizes for a socket are set when the socket is created. The default 2638 sizes used are both protocol-specific and implementation-defined. The sizes may be changed | 2639 using the setsockopt( ) function. | 2640 2.10.10 Pending Error 2641 Errors may occur asynchronously, and be reported to the socket in response to input from the 2642 network protocol. The socket stores the pending error to be reported to a user of the socket at the 2643 next opportunity. The error is returned in response to a subsequent send( ), recv( ), or getsockopt( ) 2644 operation on the socket, and the pending error is then cleared. 2645 2.10.11 Socket Receive Queue 2646 A socket has a receive queue that buffers data when they are received by the system until they 2647 are removed by a receive call. Depending on the type of the socket and the communication 2648 provider, the receive queue may also contain ancillary data such as the addressing and other 2649 protocol data associated with the normal data in the queue, and may contain out-of-band or 2650 expedited data. The limit on the queue size includes any normal, out-of-band data, datagram 2651 source addresses, and ancillary data in the queue. The description in this section applies to all 2652 sockets, even though some elements cannot be present in some instances. 2653 The contents of a receive buffer are logically structured as a series of data segments with 2654 associated ancillary data and other information. A data segment may contain normal data or 2655 out-of-band data, but never both. A data segment may complete a record if the protocol 2656 supports records (always true for types SOCK_SEQPACKET and SOCK_DGRAM). A record 2657 may be stored as more than one segment; the complete record might never be present in the 2658 receive buffer at one time, as a portion might already have been returned to the application, and 2659 another portion might not yet have been received from the communications provider. A data 2660 segment may contain ancillary protocol data, which is logically associated with the segment. 2661 Ancillary data is received as if it were queued along with the first normal data octet in the 2662 segment (if any). A segment may contain ancillary data only, with no normal or out-of-band 2663 data. For the purposes of this section, a datagram is considered to be a data segment that 2664 terminates a record, and that includes a source address as a special type of ancillary data. Data 2665 segments are placed into the queue as data is delivered to the socket by the protocol. Normal 2666 data segments are placed at the end of the queue as they are delivered. If a new segment 2667 contains the same type of data as the preceding segment and includes no ancillary data, and if 2668 the preceding segment does not terminate a record, the segments are logically merged into a 2669 single segment. 2670 The receive queue is logically terminated if an end-of-file indication has been received or a 2671 connection has been terminated. A segment shall be considered to be terminated if another 2672 segment follows it in the queue, if the segment completes a record, or if an end-of-file or other 2673 connection termination has been reported. The last segment in the receive queue shall also be 2674 considered to be terminated while the socket has a pending error to be reported. 564 Technical Standard (2000) (Draft July 31, 2000) General Information Sockets 2675 A receive operation shall never return data or ancillary data from more than one segment. 2676 2.10.12 Socket Out-of-Band Data State 2677 The handling of received out-of-band data is protocol-specific. Out-of-band data may be placed 2678 in the socket receive queue, either at the end of the queue or before all normal data in the queue. 2679 In this case, out-of-band data is returned to an application program by a normal receive call. 2680 Out-of-band data may also be queued separately rather than being placed in the socket receive 2681 queue, in which case it shall be returned only in response to a receive call that requests out-of- 2682 band data. It is protocol-specific whether an out-of-band data mark is placed in the receive 2683 queue to demarcate data preceding the out-of-band data and following the out-of-band data. An 2684 out-of-band data mark is logically an empty data segment that cannot be merged with other 2685 segments in the queue. An out-of-band data mark is never returned in response to an input 2686 operation. The sockatmark( ) function can be used to test whether an out-of-band data mark is the 2687 first element in the queue. If an out-of-band data mark is the first element in the queue when an 2688 input function is called without the MSG_PEEK option, the mark is removed from the queue and 2689 the following data (if any) are processed as if the mark had not been present. 2690 2.10.13 Connection Indication Queue 2691 Sockets that are used to accept incoming connections maintain a queue of outstanding 2692 connection indications. This queue is a list of connections that are awaiting acceptance by the 2693 application. See listen( ). 2694 2.10.14 Signals 2695 One category of event at the socket interface is the generation of signals. These signals report 2696 protocol events or process errors relating to the state of the socket. The generation or delivery of 2697 a signal does not change the state of the socket, although the generation of the signal may have 2698 been caused by a state change. 2699 The SIGPIPE signal shall be sent to a thread that attempts to send data on a socket that is no | 2700 longer able to send. In addition, the send operation fails with the error [EPIPE]. 2701 If a socket has an owner, the SIGURG signal is sent to the owner of the socket when it is notified 2702 of expedited or out-of-band data. The socket state at this time is protocol-dependent, and the 2703 status of the socket is specified in Section 2.10.17 (on page 569), Section 2.10.18 (on page 569), | 2704 and Section 2.10.19 (on page 570). Depending on the protocol, the expedited data may or may | 2705 not have arrived at the time of signal generation. | 2706 2.10.15 Asynchronous Errors 2707 If any of the following conditions occur asynchronously for a socket, the corresponding value 2708 listed below shall become the pending error for the socket: 2709 [ECONNABORTED] 2710 The connection was aborted locally. 2711 [ECONNREFUSED] 2712 For a connection-mode socket attempting a non-blocking connection, the attempt to connect 2713 was forcefully rejected. For a connectionless-mode socket, an attempt to deliver a datagram 2714 was forcefully rejected. 2715 [ECONNRESET] 2716 The peer has aborted the connection. System Interfaces, Issue 6 565 Sockets General Information 2717 [EHOSTDOWN] 2718 The destination host has been determined to be down or disconnected. 2719 [EHOSTUNREACH] 2720 The destination host is not reachable. 2721 [EMSGSIZE] 2722 For a connectionless-mode socket, the size of a previously sent datagram prevented 2723 delivery. 2724 [ENETDOWN] 2725 The local network connection is not operational. 2726 [ENETRESET] 2727 The connection was aborted by the network. 2728 [ENETUNREACH] 2729 The destination network is not reachable. 2730 2.10.16 Use of Options 2731 There are a number of socket options which either specialize the behavior of a socket or provide 2732 useful information. These options may be set at different protocol levels and are always present 2733 at the uppermost ``socket'' level. 2734 Socket options are manipulated by two functions, getsockopt( ) and setsockopt( ). These functions 2735 allow an application program to customize the behavior and characteristics of a socket to 2736 provide the desired effect. 2737 All of the options have default values. The type and meaning of these values is defined by the 2738 protocol level to which they apply. Instead of using the default values, an application program 2739 may choose to customize one or more of the options. However, in the bulk of cases, the default 2740 values are sufficient for the application. 2741 Some of the options are used to enable or disable certain behavior within the protocol modules 2742 (for example, turn on debugging) while others may be used to set protocol-specific information 2743 (for example, IP time-to-live on all the application's outgoing packets). As each of the options is 2744 introduced, its effect on the underlying protocol modules is described. 2745 Table 2-4 shows the value for the socket level. 2746 Table 2-4 Value of Level for Socket Options _______________________________________________________ 2747 _ Name Description ______________________________________________________ 2748 _ SOL_SOCKET Options are intended for the sockets level. ______________________________________________________ 2749 Table 2-5 (on page 567) lists those options present at the socket level; that is, when the level 2750 parameter of the getsockopt( ) or setsockopt( ) function is SOL_SOCKET, the types of the option 2751 value parameters associated with each option, and a brief synopsis of the meaning of the option 2752 value parameter. Unless otherwise noted, each may be examined with getsockopt( ) and set with 2753 setsockopt( ) on all types of socket. 566 Technical Standard (2000) (Draft July 31, 2000) General Information Sockets 2754 Table 2-5 Socket-Level Options __________________________________________________________________________________ 2755 _ Option Parameter Type Parameter Meaning _________________________________________________________________________________ 2756 SO_BROADCAST (void *) int Non-zero requests permission to transmit 2757 broadcast datagrams (SOCK_DGRAM sockets 2758 only). 2759 SO_DEBUG int Non-zero requests debugging in underlying 2760 protocol modules. 2761 SO_DONTROUTE int Non-zero requests bypass of normal routing; 2762 route based on destination address only. 2763 SO_ERROR int Requests and clears pending error information 2764 on the socket (getsockopt( ) only). 2765 SO_KEEPALIVE int Non-zero requests periodic transmission of 2766 keepalive messages (protocol-specific). 2767 SO_LINGER struct linger Specify actions to be taken for queued, unsent 2768 data on close( ): linger on/off and linger time in 2769 seconds. 2770 SO_OOBINLINE int Non-zero requests that out-of-band data be 2771 placed into normal data input queue as received. 2772 SO_RCVBUF int Size of receive buffer (in bytes). 2773 SO_RCVLOWAT int Minimum amount of data to return to 2774 application for input operations (in bytes). 2775 SO_RCVTIMEO struct timeval Timeout value for a socket receive operation. 2776 SO_REUSEADDR int Non-zero requests reuse of local addresses in 2777 bind( ) (protocol-specific). 2778 SO_SNDBUF int Size of send buffer (in bytes). 2779 SO_SNDLOWAT int Minimum amount of data to send for output 2780 operations (in bytes). 2781 SO_SNDTIMEO struct timeval Timeout value for a socket send operation. 2782 SO_TYPE int Identify socket type (getsockopt( ) only). __________________________________________________________________________________ 2783 The SO_BROADCAST option requests permission to send broadcast datagrams on the socket. 2784 Support for SO_BROADCAST is protocol-specific. The default for SO_BROADCAST is that the 2785 ability to send broadcast datagrams on a socket is disabled. 2786 SO_DEBUG enables debugging in the underlying protocol modules. This can be useful for 2787 tracing the behavior of the underlying protocol modules during normal system operation. The 2788 semantics of the debug reports are implementation-defined. The default value for SO_DEBUG is | 2789 for debugging to be turned off. | 2790 SO_DONTROUTE requests that outgoing messages bypass the standard routing facilities. The 2791 destination must be on a directly-connected network, and messages are directed to the 2792 appropriate network interface according to the destination address. It is protocol-specific 2793 whether this option has any effect and how the outgoing network interface is chosen. Support 2794 for this option with each protocol is implementation-defined. | 2795 SO_ERROR is used only on getsockopt( ). When this option is specified, getsockopt( ) returns any 2796 pending error on the socket and clears the error status. It returns a value of 0 if there is no 2797 pending error. SO_ERROR may be used to check for asynchronous errors on connected 2798 connectionless-mode sockets or for other types of asynchronous errors. SO_ERROR has no 2799 default value. System Interfaces, Issue 6 567 Sockets General Information 2800 SO_KEEPALIVE enables the periodic transmission of messages on a connected socket. The 2801 behavior of this option is protocol-specific. The default value for SO_KEEPALIVE is zero, 2802 specifying that this capability is turned off. 2803 The SO_LINGER option controls the action of the interface when unsent messages are queued 2804 on a socket and a close( ) is performed. The details of this option are protocol-specific. The 2805 default value for SO_LINGER is zero, or off, for the l_onoff element of the option value and zero 2806 seconds for the linger time specified by the l_linger element. 2807 SO_OOBINLINE is valid only on protocols that support out-of-band data. The SO_OOBINLINE 2808 option requests that out-of-band data be placed in the normal data input queue as received; it is 2809 then accessible using the read( ) or recv( ) functions without the MSG_OOB flag set. The default 2810 for SO_OOBINLINE is off; that is, for out-of-band data not to be placed in the normal data input 2811 queue. 2812 SO_RCVBUF requests that the buffer space allocated for receive operations on this socket be set 2813 to the value, in bytes, of the option value. Applications may wish to increase buffer size for high 2814 volume connections, or may decrease buffer size to limit the possible backlog of incoming data. 2815 The default value for the SO_RCVBUF option value is implementation-defined, and may vary by | 2816 protocol. | 2817 The maximum value for the option for a socket may be obtained by the use of the fpathconf( ) 2818 function, using the value _PC_SOCK_MAXBUF. 2819 SO_RCVLOWAT sets the minimum number of bytes to process for socket input operations. In 2820 general, receive calls block until any (non-zero) amount of data is received, then return the 2821 smaller of the amount available or the amount requested. The default value for SO_RCVLOWAT 2822 is 1, and does not affect the general case. If SO_RCVLOWAT is set to a larger value, blocking 2823 receive calls normally wait until they have received the smaller of the low water mark value or 2824 the requested amount. Receive calls may still return less than the low water mark if an error 2825 occurs, a signal is caught, or the type of data next in the receive queue is different than that 2826 returned (for example, out-of-band data). As mentioned previously, the default value for 2827 SO_RCVLOWAT is 1 byte. It is implementation-defined whether the SO_RCVLOWAT option | 2828 can be set. 2829 SO_RCVTIMEO is an option to set a timeout value for input operations. It accepts a timeval 2830 structure with the number of seconds and microseconds specifying the limit on how long to wait 2831 for an input operation to complete. If a receive operation has blocked for this much time without 2832 receiving additional data, it returns with a partial count or errno set to [EWOULDBLOCK] if no 2833 data were received. The default for this option is the value zero, which indicates that a receive 2834 operation will not timeout. It is implementation-defined whether the SO_RCVTIMEO option can | 2835 be set. | 2836 SO_REUSEADDR indicates that the rules used in validating addresses supplied in a bind( ) 2837 should allow reuse of local addresses. Operation of this option is protocol-specific. The default 2838 value for SO_REUSEADDR is off; that is, reuse of local addresses is not permitted. 2839 SO_SNDBUF requests that the buffer space allocated for send operations on this socket be set to 2840 the value, in bytes, of the option value. The default value for the SO_SNDBUF option value is | 2841 implementation-defined, and may vary by protocol. The maximum value for the option for a | 2842 socket may be obtained by the use of the fpathconf( ) function, using the value 2843 _PC_SOCK_MAXBUF. 2844 SO_SNDLOWAT sets the minimum number of bytes to process for socket output operations. 2845 Most output operations process all of the data supplied by the call, delivering data to the 2846 protocol for transmission and blocking as necessary for flow control. Non-blocking output 2847 operations process as much data as permitted subject to flow control without blocking, but 568 Technical Standard (2000) (Draft July 31, 2000) General Information Sockets 2848 process no data if flow control does not allow the smaller of the send low water mark value or 2849 the entire request to be processed. A select( ) operation testing the ability to write to a socket 2850 returns true only if the send low water mark could be processed. The default value for | 2851 SO_SNDLOWAT is implementation-defined and protocol-specific. It is implementation-defined | 2852 whether the SO_SNDLOWAT option can be set. | 2853 SO_SNDTIMEO is an option to set a timeout value for the amount of time that an output 2854 function shall block because flow control prevents data from being sent. As noted in Table 2-5 2855 (on page 567), the option value is a timeval structure with the number of seconds and 2856 microseconds specifying the limit on how long to wait for an output operation to complete. If a 2857 send operation has blocked for this much time, it returns with a partial count or errno set to 2858 [EWOULDBLOCK] if no data were sent. The default for this option is the value zero, which 2859 indicates that a send operation will not timeout. It is implementation-defined whether the | 2860 SO_SNDTIMEO option can be set. | 2861 SO_TYPE is used only on getsockopt( ). When this option is specified, getsockopt( ) returns the 2862 type of the socket (for example, SOCK_STREAM). This option is useful to servers that inherit 2863 sockets on start-up. SO_TYPE has no default value. 2864 2.10.17 Use of Sockets for Local UNIX Connections 2865 Support for UNIX domain sockets is mandatory. 2866 UNIX domain sockets provide process-to-process communication in a single system. 2867 2.10.17.1 Headers 2868 Symbolic constant AF_UNIX is defined in the header to identify the UNIX 2869 domain address family. The header contains other definitions used in connection 2870 with UNIX domain sockets. See the Base Definitions volume of IEEE Std. 1003.1-200x, Chapter | 2871 13, Headers. | 2872 The sockaddr_storage structure defined in is large enough to accommodate a 2873 sockaddr_un structure (see the header defined in the Base Definitions volume of | 2874 IEEE Std. 1003.1-200x, Chapter 13, Headers) and is aligned at an appropriate boundary so that | 2875 pointers to it can be cast as pointers to sockaddr_un structures and used to access the fields of 2876 those structures without alignment problems. When a sockaddr_storage structure is cast as a 2877 sockaddr_un structure, the ss_family field maps onto the sun_family field. 2878 2.10.18 Use of Sockets over Internet Protocols Based on IPv4 2879 Support for sockets over Internet protocols based on IPv4 is mandatory. 2880 2.10.18.1 Headers 2881 Symbolic constant AF_INET is defined in the header to identify the IPv4 Internet 2882 address family. The header contains other definitions used in connection with 2883 IPv4 Internet sockets. See the Base Definitions volume of IEEE Std. 1003.1-200x, Chapter 13, | 2884 Headers. | 2885 The sockaddr_storage structure defined in is large enough to accommodate a 2886 sockaddr_in structure (see the header defined in the Base Definitions volume of | 2887 IEEE Std. 1003.1-200x, Chapter 13, Headers) and is aligned at an appropriate boundary so that | 2888 pointers to it can be cast as pointers to sockaddr_in structures and used to access the fields of 2889 those structures without alignment problems. When a sockaddr_storage structure is cast as a 2890 sockaddr_in structure, the ss_family field maps onto the sin_family field. System Interfaces, Issue 6 569 Sockets General Information 2891 2.10.19 Use of Sockets over Internet Protocols Based on IPv6 2892 IP6 This section describes extensions to support sockets over Internet protocols based on IPv6. This | 2893 functionality is dependent on support of the IPV6 option (and the rest of this section is not | 2894 further shaded for this option). | 2895 To enable smooth transition from IPv4 to IPv6, the features defined in this section may, in certain 2896 circumstances, also be used in connection with IPv4; see Section 2.10.19.2 (on page 571). 2897 2.10.19.1 Addressing 2898 IPv6 overcomes the addressing limitations of previous versions by using 128-bit addresses 2899 instead of 32-bit addresses. The IPv6 address architecture is described in RFC 2373. 2900 There are three kinds of IPv6 address: 2901 Unicast 2902 Identifies a single interface. 2903 A unicast address can be global, link-local (designed for use on a single link), or site-local 2904 (designed for systems not connected to the Internet). Link-local and site-local addresses 2905 need not be globally unique. 2906 Anycast 2907 Identifies a set of interfaces such that a packet sent to the address can be delivered to any 2908 member of the set. 2909 An anycast address is similar to a unicast address; the nodes to which an anycast address is 2910 assigned must be explicitly configured to know that it is an anycast address. 2911 Multicast 2912 Identifies a set of interfaces such that a packet sent to the address should be delivered to 2913 every member of the set. 2914 An application can send multicast datagrams by simply specifying an IPv6 multicast 2915 address in the address argument of sendto( ). To receive multicast datagrams, an application 2916 must join the multicast group (using setsockopt( ) with IPV6_JOIN_GROUP) and must bind 2917 to the socket the UDP port on which datagrams will be received. Some applications should 2918 also bind the multicast group address to the socket, to prevent other datagrams destined to 2919 that port from being delivered to the socket. 2920 A multicast address can be global, node-local, link-local, site-local, or organization-local. 2921 The following special IPv6 addresses are defined: 2922 Unspecified 2923 An address that is not assigned to any interface and is used to indicate the absence of an 2924 address. 2925 Loopback 2926 A unicast address that is not assigned to any interface and can be used by a node to send 2927 packets to itself. 2928 Two sets of IPv6 addresses are defined to correspond to IPv4 addresses: 2929 IPv4-compatible addresses 2930 These are assigned to nodes that support IPv6 and can be used when traffic is ``tunneled'' 2931 through IPv4. 2932 IPv4-mapped addresses 2933 These are used to represent IPv4 addresses in IPv6 address format; see Section 2.10.19.2 (on 570 Technical Standard (2000) (Draft July 31, 2000) General Information Sockets 2934 page 571). 2935 Note that the unspecified address and the loopback address must not be treated as IPv4- 2936 compatible addresses. 2937 2.10.19.2 Compatibility with IPv4 2938 The API provides the ability for IPv6 applications to interoperate with applications using IPv4, 2939 by using IPv4-mapped IPv6 addresses. These addresses can be generated automatically by the 2940 getipnodebyname( ) function when the specified host has only IPv4 addresses (as described in 2941 endhostent( )). 2942 Applications may use AF_INET6 sockets to open TCP connections to IPv4 nodes, or send UDP 2943 packets to IPv4 nodes, by simply encoding the destination's IPv4 address as an IPv4-mapped 2944 IPv6 address, and passing that address, within a sockaddr_in6 structure, in the connect( ), 2945 sendto( ) or sendmsg( ) function. When applications use AF_INET6 sockets to accept TCP 2946 connections from IPv4 nodes, or receive UDP packets from IPv4 nodes, the system returns the 2947 peer's address to the application in the accept( ), recvfrom( ), recvmsg( ), or getpeername( ) function 2948 using a sockaddr_in6 structure encoded this way. If a node has an IPv4 address, then the 2949 implementation may allow applications to communicate using that address via an AF_INET6 2950 socket. In such a case, the address will be represented at the API by the corresponding IPv4- 2951 mapped IPv6 address. Also, the implementation may allow an AF_INET6 socket bound to 2952 in6addr_any to receive inbound connections and packets destined to one of the node's IPv4 2953 addresses. 2954 An application may use AF_INET6 sockets to bind to a node's IPv4 address by specifying the 2955 address as an IPv4-mapped IPv6 address in a sockaddr_in6 structure in the bind( ) function. For 2956 an AF_INET6 socket bound to a node's IPv4 address, the system returns the address in the 2957 getsockname( ) function as an IPv4-mapped IPv6 address in a sockaddr_in6 structure. 2958 2.10.19.3 Interface Identification 2959 Each local interface is assigned a unique positive integer as a numeric index. Indexes start at 1; 2960 zero is not used. There may be gaps so that there is no current interface for a particular positive 2961 index. Each interface also has a unique implementation-defined name. | 2962 2.10.19.4 Options 2963 The following options apply at the IPPROTO_IPV6 level: 2964 IPV6_JOIN_GROUP 2965 When set via setsockopt( ), it joins the application to a multicast group on an interface 2966 (identified by its index) and addressed by a given multicast address, enabling packets sent 2967 to that address to be read via the socket. If the interface index is specified as zero, the 2968 system selects the interface (for example, by looking up the address in a routing table and 2969 using the resulting interface). 2970 An attempt to read this option using getsockopt( ) results in an [EOPNOTSUPP] error. 2971 The value of this option is an ipv6_mreq structure. 2972 IPV6_LEAVE_GROUP 2973 When set via setsockopt( ), it removes the application from the multicast group on an 2974 interface (identified by its index) and addressed by a given multicast address. 2975 An attempt to read this option using getsockopt( ) results in an [EOPNOTSUPP] error. System Interfaces, Issue 6 571 Sockets General Information 2976 The value of this option is an ipv6_mreq structure. 2977 IPV6_MULTICAST_HOPS 2978 The value of this option is the hop limit for outgoing multicast IPv6 packets sent via the 2979 socket. Its possible values are the same as those of IPV6_UNICAST_HOPS. If the 2980 IPV6_MULTICAST_HOPS option is not set, a value of 1 is assumed. This option can be set 2981 via setsockopt( ) and read via getsockopt( ). 2982 IPV6_MULTICAST_IF 2983 The index of the interface to be used for outgoing multicast packets. It can be set via 2984 setsockopt( ) and read via getsockopt( ). 2985 IPV6_MULTICAST_LOOP 2986 This option controls whether outgoing multicast packets should be delivered back to the 2987 local application when the sending interface is itself a member of the destination multicast 2988 group. If it is set to 1 they are delivered. If it is set to 0 they are not. Other values result in an 2989 [EINVAL] error. This option can be set via setsockopt( ) and read via getsockopt( ). 2990 IPV6_UNICAST_HOPS 2991 The value of this option is the hop limit for outgoing unicast IPv6 packets sent via the 2992 socket. If the option is not set, or is set to -1, the system selects a default value. Attempts to 2993 set a value less than -1 or greater than 255 result in an [EINVAL] error. This option can be 2994 set via setsockopt( ) and read via getsockopt( ). 2995 An [EOPNOTSUPP] error results if IPV6_JOIN_GROUP or IPV6_LEAVE_GROUP is used with 2996 getsockopt( ). 2997 2.10.19.5 Headers 2998 Symbolic constant AF_INET6 is defined in the header to identify the IPv6 | 2999 Internet address family. See the Base Definitions volume of IEEE Std. 1003.1-200x, Chapter 13, | 3000 Headers. | 3001 The sockaddr_storage structure defined in is large enough to accommodate a 3002 sockaddr_in6 structure (see the header defined in the Base Definitions volume of | 3003 IEEE Std. 1003.1-200x, Chapter 13, Headers) and is aligned at an appropriate boundary so that | 3004 pointers to it can be cast as pointers to sockaddr_in6 structures and used to access the fields of 3005 those structures without alignment problems. When a sockaddr_storage structure is cast as a 3006 sockaddr_in6 structure, the ss_family field maps onto the sin6_family field. 3007 The , , and headers contain other definitions used in 3008 connection with IPv6 Internet sockets; see the Base Definitions volume of IEEE Std. 1003.1-200x, | 3009 Chapter 13, Headers. | 572 Technical Standard (2000) (Draft July 31, 2000) General Information Tracing 3010 2.11 Tracing | 3011 TRC This section describes extensions to support tracing of user applications. This functionality is | 3012 dependent on support of the Trace option (and the rest of this section is not further shaded for | 3013 this option). | 3014 The tracing facilities defined in IEEE Std. 1003.1-200x allow a process to select a set of trace event | 3015 types, to activate a trace stream of the selected trace events as they occur in the flow of | 3016 execution, and to retrieve the recorded trace events. | 3017 The tracing operation relies on three logically different components: the traced process, the | 3018 controller process, and the analyzer process. During the execution of the traced process, when a | 3019 trace point is reached, a trace event is recorded into the trace streams created for that process in | 3020 which the associated trace event type identifier is not being filtered out. The controller process | 3021 controls the operation of recording the trace events into the trace stream. It shall be able to: | 3022 * Initialize the attributes of a trace stream | 3023 * Create the trace stream (for a specified traced process) using those attributes | 3024 * Start and stop tracing for the trace stream | 3025 * Filter the type of trace events to be recorded, if the Trace Event Filter option is supported | 3026 * Shut a trace stream down | 3027 These operations can be done for an active trace stream. The analyzer process retrieves the | 3028 traced events either at runtime, when the trace stream has not yet been shut down, but is still | 3029 recording trace events; or after opening a trace log that had been previously recorded and shut | 3030 down. These three logically different operations can be performed by the same process, or can be | 3031 distributed into different processes. | 3032 A trace stream identifier can be created by a call to posix_trace_create( ), | 3033 posix_trace_create_withlog( ), or posix_trace_open( ). The posix_trace_create( ) and | 3034 posix_trace_create_withlog( ) functions should be used by a controller process. The | 3035 posix_trace_open( ) should be used by an analyzer process. | 3036 The tracing functions can serve different purposes. One purpose is debugging the possibly pre- | 3037 instrumented code, while another is post-mortem fault analysis. These two potential uses differ | 3038 in that the first requires pre-filtering capabilities to avoid overwhelming the trace stream and | 3039 permits focusing on expected information; while the second needs comprehensive trace | 3040 capabilities in order to be able to record all types of information. | 3041 The events to be traced belong to two classes: | 3042 1. User trace events (generated by the application instrumentation) | 3043 2. System trace events (generated by the operating system) | 3044 The trace interface defines several system trace event types associated with control of and | 3045 operation of the trace stream. This small set of system trace events includes the minimum | 3046 required to interpret correctly the trace event information present in the stream. Other desirable | 3047 system trace events for some particular application profile may be implemented and are | 3048 encouraged; for example, process and thread scheduling, signal occurrence, and so on. | 3049 Each traced process shall have a mapping of the trace event names to trace event type identifiers | 3050 that have been defined for that process. Each active trace stream shall have a mapping that | 3051 incorporates all the trace event type identifiers predefined by the trace system plus all the | 3052 mappings of trace event names to trace event type identifiers of the processes that are being | 3053 traced into that trace stream. These mappings are defined from the instrumented application by | System Interfaces, Issue 6 573 Tracing General Information 3054 calling the posix_trace_eventid_open( ) function and from the controller process by calling the | 3055 posix_trace_trid_eventid_open( ) function. For a pre-recorded trace stream, the list of trace event | 3056 types is obtained from the pre-recorded trace log. | 3057 The st_ctime and st_mtime fields of a file associated with an active trace stream shall be marked | 3058 for update every time any of the tracing operations modifies that file. | 3059 The st_atime field of a file associated with a trace stream shall be marked for update every time | 3060 any of the tracing operations causes data to be read from that file. | 3061 Results are undefined if the application performs any operation on a file descriptor associated | 3062 with an active or pre-recorded trace stream until posix_trace_shutdown( ) or posix_trace_close( ) is | 3063 called for that trace stream. | 3064 The main purpose of this option is to define a complete set of functions and concepts that allow | 3065 a portable application to be traced from birth to death, whatever its realtime constraints and | 3066 properties. | 3067 2.11.1 Tracing Data Definitions | 3068 2.11.1.1 Structures | 3069 The header shall define the posix_trace_status_info and posix_trace_event_info structures | 3070 described below. Implementations may add extensions to these structures. | 3071 posix_trace_status_info Structure | 3072 To facilitate control of a trace stream, information about the current state of an active trace | 3073 stream can be obtained dynamically. This structure is returned by a call to the | 3074 posix_trace_get_status( ) function. | 3075 The posix_trace_status_info structure defined in shall contain at least the following | 3076 members: | 3077 ________________________________________________________________________________ | 3078 _ Member Type Member Name Description _______________________________________________________________________________ || 3079 int posix_stream_status The operating mode of the trace stream. | 3080 int posix_stream_full_status The full status of the trace stream. | 3081 int posix_stream_overrun_status Indicates whether trace events were | || 3082 lost in the trace stream. | | _ _______________________________________________________________________________ ||||| 3083 If the Trace Log option is supported in addition to the Trace option, the posix_trace_status_info | 3084 structure defined in shall contain at least the following additional members: | 3085 _____________________________________________________________________________ | 3086 _ Member Type Member Name Description ____________________________________________________________________________ || 3087 int posix_stream_flush_status Indicates whether a flush is in progress. | 3088 int posix_stream_flush_error Indicates whether any error occurred | || 3089 during the last flush operation. | | 3090 int posix_log_overrun_status Indicates whether trace events were | || 3091 lost in the trace log. | | 3092 _int posix_log_full_status The full status of the trace log. ____________________________________________________________________________ |||||| 3093 The posix_stream_status member indicates the operating mode of the trace stream and shall have | 3094 one of the following values defined by manifest constants in the header: | 574 Technical Standard (2000) (Draft July 31, 2000) General Information Tracing 3095 POSIX_TRACE_RUNNING | 3096 Tracing is in progress; that is, the trace stream is accepting trace events. | 3097 POSIX_TRACE_SUSPENDED | 3098 The trace stream is not accepting trace events. The tracing operation has not yet started or | 3099 has stopped, either following a posix_trace_stop( ) function call or because the trace resources | 3100 are exhausted. | 3101 The posix_stream_full_status member indicates the full status of the trace stream, and it shall have | 3102 one of the following values defined by manifest constants in the header: | 3103 POSIX_TRACE_FULL | 3104 The space in the trace stream for trace events is exhausted. | 3105 POSIX_TRACE_NOT_FULL | 3106 There is still space available in the trace stream. | 3107 The combination of the posix_stream_status and posix_stream_full_status members also indicates | 3108 the actual status of the stream. The status shall be interpreted as follows: | 3109 POSIX_TRACE_RUNNING and POSIX_TRACE_NOT_FULL | 3110 This status combination indicates that tracing is in progress, and there is space available for | 3111 recording more trace events. | 3112 POSIX_TRACE_RUNNING and POSIX_TRACE_FULL | 3113 This status combination indicates that tracing is in progress and that the trace stream is full | 3114 of trace events. This status combination cannot occur unless the stream-full-policy is set to | 3115 POSIX_TRACE_LOOP. The trace stream contains trace events recorded during a moving | 3116 time window of prior trace events, and some older trace events may have been overwritten | 3117 and thus lost. | 3118 POSIX_TRACE_SUSPENDED and POSIX_TRACE_NOT_FULL | 3119 This status combination indicates that tracing has not yet been started, has been stopped by | 3120 the posix_trace_stop( ) function, or has been cleared by the posix_trace_clear( ) function. | 3121 POSIX_TRACE_SUSPENDED and POSIX_TRACE_FULL | 3122 This status combination indicates that tracing has been stopped by the implementation | 3123 because the stream-full-policy attribute was POSIX_TRACE_UNTIL_FULL and trace | 3124 resources were exhausted, or that the trace stream was stopped by the function | 3125 posix_trace_stop( ) at a time when trace resources were exhausted. | 3126 The posix_stream_overrun_status member indicates whether trace events were lost in the trace | 3127 stream, and shall have one of the following values defined by manifest constants in the | 3128 header: | 3129 POSIX_TRACE_OVERRUN | 3130 At least one trace event was lost and thus was not recorded in the trace stream. | 3131 POSIX_TRACE_NO_OVERRUN | 3132 No trace events were lost. | 3133 When the corresponding trace stream is created, the posix_stream_overrun_status member shall be | 3134 set to POSIX_TRACE_NO_OVERRUN. | 3135 Whenever an overrun occurs, posix_stream_overrun_status member shall be set to | 3136 POSIX_TRACE_OVERRUN. | 3137 An overrun occurs when: | System Interfaces, Issue 6 575 Tracing General Information 3138 * The policy is POSIX_TRACE_LOOP and a recorded trace event is overwritten. | 3139 * The policy is POSIX_TRACE_UNTIL_FULL and the trace stream is full when a trace event is | 3140 generated. | 3141 * If the Trace Log option is supported, the policy is POSIX_TRACE_FLUSH and at least one | 3142 trace event is lost while flushing the trace stream to the trace log. | 3143 The posix_stream_overrun_status member is reset to zero after its value is read. | 3144 If the Trace Log option is supported in addition to the Trace option, the posix_stream_flush_status, | 3145 posix_stream_flush_error, posix_log_overrun_status, and posix_log_full_status members are defined | 3146 as follows; otherwise, they are undefined. | 3147 The posix_stream_flush_status member indicates whether a flush operation is being performed | 3148 and shall have one of the following values defined by manifest constants in the header | 3149 : | 3150 POSIX_TRACE_FLUSHING | 3151 The trace stream is currently being flushed to the trace log. | 3152 POSIX_TRACE_NOT_FLUSHING | 3153 No flush operation is in progress. | 3154 The posix_stream_flush_status member shall be set to POSIX_TRACE_FLUSHING if a flush | 3155 operation is in progress either due to a call to the posix_trace_flush( ) function (explicit or caused | 3156 by a trace stream shutdown operation) or because the trace stream has become full with the | 3157 stream-full-policy attribute set to POSIX_TRACE_FLUSH. The posix_stream_flush_status member | 3158 shall be set to POSIX_TRACE_NOT_FLUSHING if no flush operation is in progress. | 3159 The posix_stream_flush_error member shall be set to zero if no error occurred during flushing. If | 3160 an error occurred during a previous flushing operation, the posix_stream_flush_error member | 3161 shall be set to the value of the first error that occurred. If more than one error occurs while | 3162 flushing, error values after the first shall be discarded. The posix_stream_flush_error member is | 3163 reset to zero after its value is read. | 3164 The posix_log_overrun_status member indicates whether trace events were lost in the trace log, | 3165 and shall have one of the following values defined by manifest constants in the | 3166 header: | 3167 POSIX_TRACE_OVERRUN | 3168 At least one trace event was lost. | 3169 POSIX_TRACE_NO_OVERRUN | 3170 No trace events were lost. | 3171 When the corresponding trace stream is created, the posix_log_overrun_status member shall be set | 3172 to POSIX_TRACE_NO_OVERRUN. Whenever an overrun occurs, this status shall be set to | 3173 POSIX_TRACE_OVERRUN. The posix_log_overrun_status member is reset to zero after its value | 3174 is read. | 3175 The posix_log_full_status member indicates the full status of the trace log, and it shall have one of | 3176 the following values defined by manifest constants in the header: | 3177 POSIX_TRACE_FULL | 3178 The space in the trace log is exhausted. | 3179 POSIX_TRACE_NOT_FULL | 3180 There is still space available in the trace log. | 576 Technical Standard (2000) (Draft July 31, 2000) General Information Tracing 3181 The posix_log_full_status member is only meaningful if the log-full-policy attribute is either | 3182 POSIX_TRACE_UNTIL_FULL or POSIX_TRACE_LOOP. | 3183 For an active trace stream without log, that is created by the posix_trace_create( ) function, the | 3184 posix_log_overrun_status member shall be set to POSIX_TRACE_NO_OVERRUN and the | 3185 posix_log_full_status member shall be set to POSIX_TRACE_NOT_FULL. | 3186 posix_trace_event_info Structure | 3187 The trace event structure posix_trace_event_info contains the information for one recorded | 3188 trace event. This structure is returned by the set of functions posix_trace_getnext_event( ), | 3189 posix_trace_timedgetnext_event( ), and posix_trace_trygetnext_event( ). | 3190 The posix_trace_event_info structure defined in shall contain at least the following | 3191 members: | 3192 ____________________________________________________________________________________ | 3193 _ Member Type Member Name Description ___________________________________________________________________________________ || 3194 trace_event_id_t posix_event_id Trace event type identification. | 3195 pid_t posix_pid Process ID of the process that generated the | || 3196 trace event. | | 3197 void * posix_prog_address Address at which the trace point was invoked. | 3198 int posix_truncation_status Status about the truncation of the data | || 3199 associated with this trace event. | | 3200 _ struct timespec posix_timestamp Time at which the trace event was generated. ___________________________________________________________________________________ |||||| 3201 In addition, if the Trace option and the Threads option are both supported, the | 3202 posix_trace_event_info structure defined in shall contain the following additional | 3203 member: | 3204 _______________________________________________________ | 3205 _ Member Type Member Name Description ______________________________________________________ || 3206 pthread_t posix_thread_id Thread ID of the thread | || 3207 that generated the trace | | 3208 event. | | _ ______________________________________________________ ||||| 3209 The posix_event_id member represents the identification of the trace event type and its value is | 3210 not directly defined by the user. This identification is returned by a call to one of the following | 3211 functions: posix_trace_trid_eventid_open( ), posix_trace_eventtypelist_getnext_id( ), or | 3212 posix_trace_eventid_open( ). The name of the trace event type can be obtained by calling | 3213 posix_trace_eventid_get_name( ). | 3214 The posix_pid is the process identifier of the traced process which generated the trace event. If | 3215 the posix_event_id member is one of the implementation-defined system trace events and that | 3216 trace event is not associated with any process, the posix_pid member shall be set to zero. | 3217 For a user trace event, the posix_prog_address member is the process mapped address of the point | 3218 at which the associated call to the posix_trace_event( ) function was made. For a system trace | 3219 event, if the trace event is caused by a system service explicitly called by the application, the | 3220 posix_prog_address member shall be the address of the process at the point where the call to that | 3221 system service was made. | 3222 The posix_truncation_status member defines whether the data associated with a trace event has | 3223 been truncated at the time the trace event was generated, or at the time the trace event was read | 3224 from the trace stream, or (if the Trace Log option is supported) from the trace log (see the event | 3225 argument from the posix_trace_getnext_event( ) function). The posix_truncation_status member | System Interfaces, Issue 6 577 Tracing General Information 3226 shall have one of the following values defined by manifest constants in the header: | 3227 POSIX_TRACE_NOT_TRUNCATED | 3228 All the traced data is available. | 3229 POSIX_TRACE_TRUNCATED_RECORD | 3230 Data was truncated at the time the trace event was generated. | 3231 POSIX_TRACE_TRUNCATED_READ | 3232 Data was truncated at the time the trace event was read from a trace stream or a trace log | 3233 because the reader's buffer was too small. This truncation status overrides the | 3234 POSIX_TRACE_TRUNCATED_RECORD status. | 3235 The posix_timestamp member shall be the time at which the trace event was generated. The clock | 3236 used is implementation-defined, but the resolution of this clock can be retrieved by a call to the | 3237 posix_trace_attr_getclockres( ) function. | 3238 If the Threads option is supported in addition to the Trace option: | 3239 * The posix_thread_id member is the identifier of the thread that generated the trace event. If | 3240 the posix_event_id member is one of the implementation-defined system trace events and that | 3241 trace event is not associated with any thread, the posix_thread_id member shall be set to zero. | 3242 Otherwise, this member is undefined. | 3243 2.11.1.2 Trace Stream Attributes | 3244 Trace streams have attributes that compose the posix_trace_attr_t trace stream attributes object. | 3245 This object shall contain at least the following attributes: | 3246 * The generation-version attribute identifies the origin and version of the trace system. | 3247 * The trace-name attribute is a character string defined by the trace controller, and that | 3248 identifies the trace stream. | 3249 * The creation-time attribute represents the time of the creation of the trace stream. | 3250 * The clock-resolution attribute defines the clock resolution of the clock used to generate | 3251 timestamps. | 3252 * The stream-min-size attribute defines the minimum size in bytes of the trace stream strictly | 3253 reserved for the trace events. | 3254 * The stream-full-policy attribute defines the policy followed when the trace stream is full; its | 3255 value is POSIX_TRACE_LOOP, POSIX_TRACE_UNTIL_FULL, or POSIX_TRACE_FLUSH. | 3256 * The max-data-size attribute defines the maximum record size in bytes of a trace event. | 3257 In addition, if the Trace option and the Trace Inherit option are both supported, the | 3258 posix_trace_attr_t trace stream creation attributes object shall contain at least the following | 3259 attributes: | 3260 * The inheritance attribute specifies whether a newly created trace stream will inherit tracing in | 3261 its parent's process trace stream. It is either POSIX_TRACE_INHERITED or | 3262 POSIX_TRACE_CLOSE_FOR_CHILD. | 3263 In addition, if the Trace option and the Trace Log option are both supported, the | 3264 posix_trace_attr_t trace stream creation attributes object shall contain at least the following | 3265 attribute: | 3266 * If the file type corresponding to the trace log supports the POSIX_TRACE_LOOP or the | 3267 POSIX_TRACE_UNTIL_FULL policies, the log-max-size attribute defines the maximum size | 578 Technical Standard (2000) (Draft July 31, 2000) General Information Tracing 3268 in bytes of the trace log associated with an active trace stream. Other stream data-for | 3269 example, trace attribute values-shall not be included in this size. | 3270 * The log-full-policy attribute defines the policy of a trace log associated with an active trace | 3271 stream to be POSIX_TRACE_LOOP, POSIX_TRACE_UNTIL_FULL, or | 3272 POSIX_TRACE_APPEND. | 3273 2.11.2 Trace Event Type Definitions | 3274 2.11.2.1 System Trace Event Type Definitions | 3275 The following system trace event types, defined in the header, track the invocation of | 3276 the trace operations: | 3277 * POSIX_TRACE_START shall be associated with a trace start operation. | 3278 * POSIX_TRACE_STOP shall be associated with a trace stop operation. | 3279 * if the Trace Event Filter option is supported, POSIX_TRACE_FILTER shall be associated with | 3280 a trace event type filter change operation. | 3281 The following system trace event types, defined in the header, report operational trace | 3282 events: | 3283 * POSIX_TRACE_OVERFLOW shall mark the beginning of a trace overflow condition. | 3284 * POSIX_TRACE_RESUME shall mark the end of a trace overflow condition. | 3285 * If the Trace Log option is supported, POSIX_TRACE_FLUSH_START shall mark the | 3286 beginning of a flush operation. | 3287 * If the Trace Log option is supported, POSIX_TRACE_FLUSH_STOP shall mark the end of a | 3288 flush operation. | 3289 * If an implementation-defined trace error condition is reported, it shall be marked | 3290 POSIX_TRACE_ERROR. | 3291 The interpretation of a trace stream or a trace log by a trace analyzer process relies on the | 3292 information recorded for each trace event, and also on system trace events that indicate the | 3293 invocation of trace control operations and trace system operational trace events. | 3294 The POSIX_TRACE_START and POSIX_TRACE_STOP trace events specify the time windows | 3295 during which the trace stream is running. | 3296 The POSIX_TRACE_STOP trace event with an associated data that is equal to zero indicates | 3297 a call of the function posix_trace_stop( ). | 3298 The POSIX_TRACE_STOP trace event with an associated data that is different from zero | 3299 indicates an automatic stop of the trace stream (see posix_trace_attr_getstreamfullpolicy( ) | 3300 defined in the System Interfaces volume of IEEE Std. 1003.1-200x). | 3301 The POSIX_TRACE_FILTER trace event indicates that a trace event type filter value changed | 3302 while the trace stream was running. | 3303 The POSIX_TRACE_ERROR serves to inform the analyzer process that an implementation- | 3304 defined internal error of the trace system occurred. | 3305 The POSIX_TRACE_OVERFLOW trace event shall be reported with a timestamp equal to the | 3306 timestamp of the first trace event overwritten. This is an indication that some generated trace | 3307 events have been lost. | System Interfaces, Issue 6 579 Tracing General Information 3308 The POSIX_TRACE_RESUME trace event shall be reported with a timestamp equal to the | 3309 timestamp of the first valid trace event reported after the overflow condition ends and shall be | 3310 reported before this first valid trace event. This is an indication that the trace system is reliably | 3311 recording trace events after an overflow condition. | 3312 Each of these trace event types is defined by a constant trace event name and a trace_event_id_t | 3313 constant; trace event data is associated with some of these trace events. | 3314 If the Trace option is supported and the Trace Event Filter option and the Trace Log option are | 3315 not supported, the following predefined system trace events in Table 2-6 shall be defined: | 3316 Table 2-6 Trace Option: System Trace Events | _____________________________________________________________________ | 3317 Event Name Constant _ Associated Data _________________ || 3318 _ Data Type ____________________________________________________________________ | | 3319 "posix_trace_error" POSIX_TRACE_ERROR _ error _________________ || 3320 _ int ____________________________________________________________________ || 3321 _ "posix_trace_start" POSIX_TRACE_START None. ____________________________________________________________________ || 3322 "posix_trace_stop" POSIX_TRACE_STOP _ auto _________________ || 3323 _ int ____________________________________________________________________ | | 3324 _ "posix_trace_overflow" POSIX_TRACE_OVERFLOW None. ____________________________________________________________________ || 3325 _ "posix_trace_resume" POSIX_TRACE_RESUME None. ____________________________________________________________________ |||||| 3326 If the Trace option and the Trace Event Filter option are both supported, and if the Trace Log | 3327 option is not supported, the following predefined system trace events in Table 2-7 shall be | 3328 defined: | 3329 Table 2-7 Trace and Trace Event Filter Options: System Trace Events | ______________________________________________________________________ | 3330 Event Name Constant _ Associated Data _________________ || 3331 _ Data Type _____________________________________________________________________ | | 3332 "posix_trace_error" POSIX_TRACE_ERROR _ error _________________ || 3333 _ int _____________________________________________________________________ || 3334 "posix_trace_start" POSIX_TRACE_START _ event_filter _________________ || 3335 _ trace_event_set_t _____________________________________________________________________ || 3336 "posix_trace_stop" POSIX_TRACE_STOP _ auto _________________ | | 3337 _ int _____________________________________________________________________ || 3338 "posix_trace_filter" POSIX_TRACE_FILTER old_event_filter | 3339 _ new_event_filter _________________ | | 3340 _ trace_event_set_t _____________________________________________________________________ || 3341 _ "posix_trace_overflow" POSIX_TRACE_OVERFLOW None. _____________________________________________________________________ || 3342 _ "posix_trace_resume" POSIX_TRACE_RESUME None. _____________________________________________________________________ |||||| 3343 If the Trace option and the Trace Log option are both supported, and if the Trace Event Filter | 3344 option is not supported, the following predefined system trace events in Table 2-8 (on page 581) | 3345 shall be defined: | 580 Technical Standard (2000) (Draft July 31, 2000) General Information Tracing 3346 Table 2-8 Trace and Trace Log Options: System Trace Events | _________________________________________________________________________ | 3347 Event Name Constant _ Associated Data _________________ || 3348 _ Data Type ________________________________________________________________________ | | 3349 "posix_trace_error" POSIX_TRACE_ERROR error | 3350 - | 3351 _ int ________________________________________________________________________ || 3352 _ "posix_trace_start" POSIX_TRACE_START None. ________________________________________________________________________ || 3353 "posix_trace_stop" POSIX_TRACE_STOP _ auto _________________ || 3354 _ int ________________________________________________________________________ | | 3355 _ "posix_trace_overflow" POSIX_TRACE_OVERFLOW None. ________________________________________________________________________ || 3356 _ "posix_trace_resume" POSIX_TRACE_RESUME None. ________________________________________________________________________ || 3357 _ "posix_trace_flush_start" POSIX_TRACE_FLUSH_START None. ________________________________________________________________________ || 3358 _ "posix_trace_flush_stop" POSIX_TRACE_FLUSH_STOP None. ________________________________________________________________________ |||||| 3359 If the Trace option, the Trace Event Filter option, and the Trace Log option are all supported, the | 3360 following predefined system trace events in Table 2-9 shall be defined: | 3361 Table 2-9 Trace, Trace Log, and Trace Event Filter Options: System Trace Events | __________________________________________________________________________ | 3362 Event Name Constant _ Associated Data _________________ || 3363 _ Data Type _________________________________________________________________________ | | 3364 "posix_trace_error" POSIX_TRACE_ERROR _ error _________________ || 3365 _ int _________________________________________________________________________ || 3366 "posix_trace_start" POSIX_TRACE_START _ event_filter _________________ || 3367 _ trace_event_set_t _________________________________________________________________________ || 3368 "posix_trace_stop" POSIX_TRACE_STOP _ auto _________________ | | 3369 _ int _________________________________________________________________________ || 3370 "posix_trace_filter" POSIX_TRACE_FILTER old_event_filter | 3371 _ new_event_filter _________________ | | 3372 _ trace_event_set_t _________________________________________________________________________ || 3373 _ "posix_trace_overflow" POSIX_TRACE_OVERFLOW None. _________________________________________________________________________ || 3374 _ "posix_trace_resume" POSIX_TRACE_RESUME None. _________________________________________________________________________ || 3375 _ "posix_trace_flush_start" POSIX_TRACE_FLUSH_START None. _________________________________________________________________________ || 3376 _ "posix_trace_flush_stop" POSIX_TRACE_FLUSH_STOP None. _________________________________________________________________________ |||||| 3377 2.11.2.2 User Trace Event Type Definitions | 3378 The user trace event POSIX_TRACE_UNNAMED_USEREVENT shall be defined in the | 3379 header. If the limit of per-process user trace event names represented by | 3380 {TRACE_USER_EVENT_MAX} has already been reached, this predefined user event shall be | 3381 returned when the application tries to register more events than allowed. The data associated | 3382 with this trace event is application-defined. | 3383 The following predefined user trace event in Table 2-10 (on page 582) shall be defined: | System Interfaces, Issue 6 581 Tracing General Information 3384 Table 2-10 Trace Option: User Trace Event | __________________________________________________________________________ | 3385 _ Event Name Constant _________________________________________________________________________ || 3386 _ "posix_trace_unnamed_userevent" POSIX_TRACE_UNNAMED_USEREVENT _________________________________________________________________________ ||||| 3387 2.11.3 Trace Functions | 3388 The trace interface is built and structured to improve portability through use of trace data of | 3389 opaque type. The object-oriented approach for the manipulation of trace attributes and trace | 3390 event type identifiers requires definition of many constructor and selector functions which | 3391 operate on these opaque types. Also, the trace interface must support several different tracing | 3392 roles. To facilitate reading the trace interface, the trace functions are grouped into small | 3393 functional sets supporting the three different roles: | 3394 * A trace controller process requires functions to set up and customize all the resources needed | 3395 to run a trace stream, including: | 3396 - Attribute initialization and destruction (posix_trace_attr_init( )) | 3397 - Identification information manipulation (posix_trace_attr_getgenversion( )) | 3398 - Trace system behavior modification (posix_trace_attr_getinherited( )) | 3399 - Trace stream and trace log size set (posix_trace_attr_getmaxusereventsize( )) | 3400 - Trace stream creation, flush, and shutdown (posix_trace_create( )) | 3401 - Trace stream and trace log clear (posix_trace_clear( )) | 3402 - Trace event type identifier manipulation (posix_trace_trid_eventid_open( )) | 3403 - Trace event type identifier list exploration (posix_trace_eventtypelist_getnext_id( )) | 3404 - Trace event type set manipulation (posix_trace_eventset_empty( )) | 3405 - Trace event type filter set (posix_trace_set_filter( )) | 3406 - Trace stream start and stop (posix_trace_start( )) | 3407 - Trace stream information and status read (posix_trace_get_attr( )) | 3408 * A traced process requires functions to instrument trace points: | 3409 - Trace event type identifiers definition and trace points insertion (posix_trace_event( )) | 3410 * A trace analyzer process requires functions to retrieve information from a trace stream and | 3411 trace log: | 3412 - Identification information read (posix_trace_attr_getgenversion( )) | 3413 - Trace system behavior information read (posix_trace_attr_getinherited( )) | 3414 - Trace stream and trace log size get (posix_trace_attr_getmaxusereventsize( )) | 3415 - Trace event type identifier manipulation (posix_trace_trid_eventid_open( )) | 3416 - Trace event type identifier list exploration (posix_trace_eventtypelist_getnext_id( )) | 3417 - Trace log open, rewind, and close (posix_trace_open( )) | 3418 - Trace stream information and status read (posix_trace_get_attr( )) | 3419 - trace event read (posix_trace_getnext_event( )) | 582 Technical Standard (2000) (Draft July 31, 2000) General Information Data Types 3420 2.12 Data Types 3421 All of the data types used by various functions are defined by the implementation. The 3422 following table describes some of these types. Other types referenced in the description of a 3423 function, not mentioned here, can be found in the appropriate header for that function. 3424 ___________________________________________________________________________________ 3425 _ Defined Type Description __________________________________________________________________________________ 3426 cc_t Type used for terminal special characters. 3427 clock_t Arithmetic type used for processor times, as defined in the ISO C 3428 standard. 3429 clockid_t Used for clock ID type in some timer functions. 3430 dev_t Arithmetic type used for device numbers. 3431 DIR Type representing a directory stream. 3432 div_t Structure type returned by the div( ) function. 3433 FILE Structure containing information about a file. 3434 glob_t Structure type used in path name pattern matching. 3435 fpos_t Type containing all information needed to specify uniquely every 3436 position within a file. 3437 gid_t Arithmetic type used for group IDs. 3438 iconv_t Type used for conversion descriptors. 3439 id_t Arithmetic type used as a general identifier; can be used to contain 3440 at least the largest of a pid_t, uid_t, or gid_t. 3441 ino_t Arithmetic type used for file serial numbers. 3442 key_t Arithmetic type used for XSI interprocess communication. 3443 ldiv_t Structure type returned by the ldiv( ) function. 3444 mode_t Arithmetic type used for file attributes. 3445 mqd_t Used for message queue descriptors. 3446 nfds_t Integer type used for the number of file descriptors. 3447 nlink_t Arithmetic type used for link counts. 3448 off_t Signed arithmetic type used for file sizes. 3449 pid_t Signed arithmetic type used for process and process group IDs. 3450 pthread_attr_t Used to identify a thread attribute object. 3451 pthread_cond_t Used for condition variables. 3452 pthread_condattr_t Used to identify a condition attribute object. 3453 pthread_key_t Used for thread-specific data keys. 3454 pthread_mutex_t Used for mutexes. 3455 pthread_mutexattr_t Used to identify a mutex attribute object. 3456 pthread_once_t Used for dynamic package initialization. 3457 pthread_rwlock_t Used for read-write locks. 3458 pthread_rwlockattr_t Used for read-write lock attributes. 3459 pthread_t Used to identify a thread. 3460 ptrdiff_t Signed integer type of the result of subtracting two pointers. 3461 regex_t Structure type used in regular expression matching. 3462 regmatch_t Structure type used in regular expression matching. 3463 rlim_t Unsigned arithmetic type used for limit values, to which objects of 3464 type int and off_t can be cast without loss of value. 3465 sem_t Type used in performing semaphore operations. 3466 _ sig_atomic_t Integer type of an object that can be accessed as an atomic __________________________________________________________________________________ System Interfaces, Issue 6 583 Data Types General Information 3467 ___________________________________________________________________________________ 3468 _ Defined Type Description __________________________________________________________________________________ 3469 entity, even in the presence of asynchronous interrupts. 3470 sigset_t Integer or structure type of an object used to represent sets 3471 of signals. 3472 size_t Unsigned integer type used for size of objects. 3473 speed_t Type used for terminal baud rates. 3474 ssize_t Arithmetic type used for a count of bytes or an error indication. 3475 suseconds_t Signed arithmetic type used for time in microseconds. 3476 tcflag_t Type used for terminal modes. 3477 time_t Arithmetic type used for time in seconds, as defined in the ISO C 3478 standard. 3479 timer_t Used for timer ID returned by the timer_create( ) function. 3480 uid_t Arithmetic type used for user IDs. 3481 useconds_t Integer type used for time in microseconds. 3482 va_list Type used for traversing variable argument lists. 3483 wchar_t Integer type whose range of values can represent distinct codes for 3484 all members of the largest extended character set specified by the 3485 supported locales. 3486 wctype_t Scalar type which represents a character class descriptor. 3487 wint_t Integer type capable of storing any valid value of wchar_t or 3488 WEOF. 3489 _ wordexp_t Structure type used in word expansion. __________________________________________________________________________________ 3490 | 584 Technical Standard (2000) (Draft July 31, 2000) Chapter 3 System Interfaces 3491 3492 This chapter describes the functions, macros, and external variables to support applications 3493 portability at the C-language source level. System Interfaces, Issue 6 585 FD_CLR( ) System Interfaces 3494 NAME 3495 FD_CLR - macros for synchronous I/O multiplexing 3496 SYNOPSIS 3497 #include 3498 FD_CLR(int fd, fd_set *fdset); 3499 FD_ISSET(int fd, fd_set *fdset); 3500 FD_SET(int fd, fd_set *fdset); 3501 FD_ZERO(fd_set *fdset); 3502 DESCRIPTION | 3503 Refer to select( ). 586 Technical Standard (2000) (Draft July 31, 2000) System Interfaces _Exit( ) 3504 NAME | 3505 _Exit, _exit - terminate a process | 3506 SYNOPSIS 3507 #include 3508 void _Exit(int status); | 3509 void _exit(int status); | 3510 DESCRIPTION 3511 Refer to exit( ). System Interfaces, Issue 6 587 _longjmp( ) System Interfaces 3512 NAME 3513 _longjmp, _setjmp - non-local goto 3514 SYNOPSIS 3515 XSI #include 3516 void _longjmp(jmp_buf env, int val); 3517 int _setjmp(jmp_buf env); 3518 3519 DESCRIPTION 3520 The _longjmp( ) and _setjmp( ) functions are identical to longjmp( ) and setjmp( ), respectively, with 3521 the additional restriction that _longjmp( ) and _setjmp( ) do not manipulate the signal mask. 3522 If _longjmp( ) is called even though env was never initialized by a call to _setjmp( ), or when the 3523 last such call was in a function that has since returned, the results are undefined. 3524 RETURN VALUE 3525 Refer to longjmp( ) and setjmp( ). 3526 ERRORS 3527 No errors are defined. 3528 EXAMPLES 3529 None. 3530 APPLICATION USAGE 3531 If _longjmp( ) is executed and the environment in which _setjmp( ) was executed no longer exists, 3532 errors can occur. The conditions under which the environment of the _setjmp( ) no longer exists 3533 include exiting the function that contains the _setjmp( ) call, and exiting an inner block with 3534 temporary storage. This condition might not be detectable, in which case the _longjmp( ) occurs 3535 and, if the environment no longer exists, the contents of the temporary storage of an inner block 3536 are unpredictable. This condition might also cause unexpected process termination. If the 3537 function has returned, the results are undefined. 3538 Passing longjmp( ) a pointer to a buffer not created by setjmp( ), passing _longjmp( ) a pointer to a 3539 buffer not created by _setjmp( ), passing siglongjmp( ) a pointer to a buffer not created by 3540 sigsetjmp( ), or passing any of these three functions a buffer that has been modified by the user 3541 can cause all the problems listed above, and more. 3542 The _longjmp( ) and _setjmp( ) functions are included to support programs written to historical 3543 system interfaces. New applications should use siglongjmp( ) and sigsetjmp( ) respectively. 3544 RATIONALE 3545 None. 3546 FUTURE DIRECTIONS 3547 The _longjmp( ) and _setjmp( ) functions may be marked LEGACY in a future version. | 3548 SEE ALSO 3549 longjmp( ), setjmp( ), siglongjmp( ), sigsetjmp( ), the Base Definitions volume of | 3550 IEEE Std. 1003.1-200x, | 3551 CHANGE HISTORY 3552 First released in Issue 4, Version 2. 588 Technical Standard (2000) (Draft July 31, 2000) System Interfaces _longjmp( ) 3553 Issue 5 3554 Moved from X/OPEN UNIX extension to BASE. System Interfaces, Issue 6 589 _setjmp( ) System Interfaces 3555 NAME 3556 _setjmp - set jump point for a non-local goto 3557 SYNOPSIS 3558 XSI #include 3559 int _setjmp(jmp_buf env); 3560 3561 DESCRIPTION 3562 Refer to _longjmp( ). 590 Technical Standard (2000) (Draft July 31, 2000) System Interfaces _tolower( ) 3563 NAME 3564 _tolower - transliterate uppercase characters to lowercase 3565 SYNOPSIS 3566 XSI #include 3567 int _tolower(int c); 3568 3569 DESCRIPTION 3570 The _tolower( ) macro shall be equivalent to tolower(c) except that the application shall ensure 3571 that the argument c is an uppercase letter. 3572 RETURN VALUE 3573 Upon successful completion, _tolower( ) shall return the lowercase letter corresponding to the 3574 argument passed. 3575 ERRORS 3576 No errors are defined. 3577 EXAMPLES 3578 None. 3579 APPLICATION USAGE 3580 None. 3581 RATIONALE 3582 None. 3583 FUTURE DIRECTIONS 3584 None. 3585 SEE ALSO 3586 tolower( ), isupper( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , the Base | 3587 Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale | 3588 CHANGE HISTORY 3589 First released in Issue 1. Derived from Issue 1 of the SVID. | 3590 Issue 4 3591 The RETURN VALUE section is expanded. 3592 Issue 6 3593 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 591 _toupper( ) System Interfaces 3594 NAME 3595 _toupper - transliterate lowercase characters to uppercase 3596 SYNOPSIS 3597 XSI #include 3598 int _toupper(int c); 3599 3600 DESCRIPTION 3601 The _toupper( ) macro shall be equivalent to toupper( ) except that the application shall ensure 3602 that the argument c is a lowercase letter. 3603 RETURN VALUE 3604 Upon successful completion, _toupper( ) shall return the uppercase letter corresponding to the 3605 argument passed. 3606 ERRORS 3607 No errors are defined. 3608 EXAMPLES 3609 None. 3610 APPLICATION USAGE 3611 None. 3612 RATIONALE 3613 None. 3614 FUTURE DIRECTIONS 3615 None. 3616 SEE ALSO 3617 islower( ), toupper( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , the Base | 3618 Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale | 3619 CHANGE HISTORY 3620 First released in Issue 1. Derived from Issue 1 of the SVID. | 3621 Issue 4 3622 The RETURN VALUE section is expanded. 3623 Issue 6 3624 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 592 Technical Standard (2000) (Draft July 31, 2000) System Interfaces a64l( ) 3625 NAME 3626 a64l, l64a - convert between a 32-bit integer and a radix-64 ASCII string 3627 SYNOPSIS 3628 XSI #include 3629 long a64l(const char *s); 3630 char *l64a(long value); 3631 3632 DESCRIPTION 3633 These functions are used to maintain numbers stored in radix-64 ASCII characters. This is a 3634 notation by which 32-bit integers can be represented by up to six characters; each character 3635 represents a digit in radix-64 notation. If the type long contains more than 32 bits, only the low- 3636 order 32 bits shall be used for these operations. 3637 The characters used to represent digits are '.' (dot) for 0, '/' for 1, '0' through '9' for 2-11, | 3638 'A' through 'Z' for 12-37, and 'a' through 'z' for 38-63. 3639 The a64l( ) function shall take a pointer to a radix-64 representation, in which the first digit is the 3640 least significant, and return a corresponding long value. If the string pointed to by s contains 3641 more than six characters, a64l( ) shall use the first six. If the first six characters of the string 3642 contain a null terminator, a64l( ) shall use only characters preceding the null terminator. The 3643 a64l( ) function scans the character string from left to right with the least significant digit on the 3644 left, decoding each character as a 6-bit radix-64 number. If the type long contains more than 32 3645 bits, the resulting value is sign-extended. The behavior of a64l( ) is unspecified if s is a null 3646 pointer or the string pointed to by s was not generated by a previous call to l64a( ). 3647 The l64a( ) function shall take a long argument and return a pointer to the corresponding radix- 3648 64 representation. The behavior of l64a( ) is unspecified if value is negative. 3649 The value returned by l64a( ) may be a pointer into a static buffer. Subsequent calls to l64a( ) may 3650 overwrite the buffer. 3651 The l64a( ) function need not be reentrant. A function that is not required to be reentrant is not 3652 required to be thread-safe. 3653 RETURN VALUE 3654 Upon successful completion, a64l( ) shall return the long value resulting from conversion of the 3655 input string. If a string pointed to by s is an empty string, a64l( ) shall return 0L. 3656 The l64a( ) function shall return a pointer to the radix-64 representation. If value is 0L, l64a( ) shall 3657 return a pointer to an empty string. 3658 ERRORS 3659 No errors are defined. 3660 EXAMPLES 3661 None. 3662 APPLICATION USAGE 3663 If the type long contains more than 32 bits, the result of a64l(l64a(x)) is x in the low-order 32 bits. 3664 RATIONALE 3665 This is not the same encoding as used by either encoding variant of the uuencode utility. | System Interfaces, Issue 6 593 a64l( ) System Interfaces 3666 FUTURE DIRECTIONS 3667 None. 3668 SEE ALSO 3669 strtoul( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , the Shell and Utilities | 3670 volume of IEEE Std. 1003.1-200x, uuencode | 3671 CHANGE HISTORY 3672 First released in Issue 4, Version 2. 3673 Issue 5 3674 Moved from X/OPEN UNIX extension to BASE. 3675 Normative text previously in the APPLICATION USAGE section moved to the DESCRIPTION. 3676 A note indicating that these functions need not be reentrant is added to the DESCRIPTION. 594 Technical Standard (2000) (Draft July 31, 2000) System Interfaces abort( ) 3677 NAME 3678 abort - generate an abnormal process abort 3679 SYNOPSIS 3680 #include 3681 void abort(void); 3682 DESCRIPTION 3683 CX The functionality described on this reference page is aligned with the ISO C standard. Any 3684 conflict between the requirements described here and the ISO C standard is unintentional. This 3685 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 3686 The abort( ) function shall cause abnormal process termination to occur, unless the signal 3687 SIGABRT is being caught and the signal handler does not return. 3688 CX The abnormal termination processing shall include at least the effect of fclose( ) on all open 3689 streams and the default actions defined for SIGABRT. 3690 XSI On XSI-conformant systems, in addition the abnormal termination processing shall include the | 3691 effect of fclose( ) on message catalog descriptors. | 3692 The SIGABRT signal shall be sent to the calling process as if by means of raise( ) with the 3693 argument SIGABRT. 3694 CX The status made available to wait( ) or waitpid( ) by abort( ) shall be that of a process terminated 3695 by the SIGABRT signal. The abort( ) function shall override blocking or ignoring the SIGABRT 3696 signal. 3697 RETURN VALUE 3698 The abort( ) function shall not return. 3699 ERRORS 3700 No errors are defined. 3701 EXAMPLES 3702 None. 3703 APPLICATION USAGE 3704 Catching the signal is intended to provide the application writer with a portable means to abort 3705 processing, free from possible interference from any implementation-defined library functions. If | 3706 SIGABRT is neither caught nor ignored, then the actions associated with SIGABRT defined in | 3707 Section 2.4.1 (on page 528) will be taken. | 3708 RATIONALE 3709 None. 3710 FUTURE DIRECTIONS 3711 None. 3712 SEE ALSO 3713 exit( ), kill( ), raise( ), signal( ), wait( ), waitpid( ), the Base Definitions volume of | 3714 IEEE Std. 1003.1-200x, | 3715 CHANGE HISTORY 3716 First released in Issue 1. Derived from Issue 1 of the SVID. | System Interfaces, Issue 6 595 abort( ) System Interfaces 3717 Issue 4 3718 The following changes are incorporated in this issue for alignment with the ISO C standard and 3719 the ISO POSIX-1 standard: 3720 * The argument list is explicitly defined as void. 3721 * The DESCRIPTION is revised to identify the correct order in which operations occur. It also 3722 identifies: 3723 - How the calling process is signaled 3724 - How status information is made available to the host environment 3725 - That abort( ) overrides blocking or ignoring of the SIGABRT signal 3726 * The APPLICATION USAGE section is replaced. 3727 Issue 6 3728 Extensions beyond the ISO C standard are now marked. 596 Technical Standard (2000) (Draft July 31, 2000) System Interfaces abs( ) 3729 NAME 3730 abs - return an integer absolute value 3731 SYNOPSIS 3732 #include 3733 int abs(int i); 3734 DESCRIPTION 3735 CX The functionality described on this reference page is aligned with the ISO C standard. Any 3736 conflict between the requirements described here and the ISO C standard is unintentional. This 3737 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 3738 The abs( ) function shall compute the absolute value of its integer operand, i. If the result cannot 3739 be represented, the behavior is undefined. 3740 RETURN VALUE 3741 The abs( ) function shall return the absolute value of its integer operand. 3742 ERRORS 3743 No errors are defined. 3744 EXAMPLES 3745 None. 3746 APPLICATION USAGE 3747 In two's-complement representation, the absolute value of the negative integer with largest 3748 magnitude {INT_MIN} might not be representable. 3749 RATIONALE 3750 None. 3751 FUTURE DIRECTIONS 3752 None. 3753 SEE ALSO 3754 fabs( ), labs( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 3755 CHANGE HISTORY 3756 First released in Issue 1. Derived from Issue 1 of the SVID. | 3757 Issue 4 3758 In the APPLICATION USAGE section, the phrase ``{INT_MIN} is undefined'' is replaced with 3759 ``{INT_MIN} might not be representable''. 3760 Issue 6 3761 Extensions beyond the ISO C standard are now marked. System Interfaces, Issue 6 597 accept( ) System Interfaces 3762 NAME 3763 accept - accept a new connection on a socket 3764 SYNOPSIS 3765 #include 3766 int accept(int socket, struct sockaddr *restrict address, | 3767 socklen_t *restrict address_len); | 3768 DESCRIPTION | 3769 The accept( ) function shall extract the first connection on the queue of pending connections, 3770 create a new socket with the same socket type protocol and address family as the specified 3771 socket, and allocate a new file descriptor for that socket. 3772 The accept( ) function takes the following arguments: 3773 socket Specifies a socket that was created with socket( ), has been bound to an address 3774 with bind( ), and has issued a successful call to listen( ). 3775 address Either a null pointer, or a pointer to a sockaddr structure where the address of 3776 the connecting socket shall be returned. 3777 address_len Points to a socklen_t structure which on input specifies the length of the 3778 supplied sockaddr structure, and on output specifies the length of the stored 3779 address. 3780 If address is not a null pointer, the address of the peer for the accepted connection shall be stored 3781 in the sockaddr structure pointed to by address, and the length of this address shall be stored in 3782 the object pointed to by address_len. 3783 If the actual length of the address is greater than the length of the supplied sockaddr structure, 3784 the stored address shall be truncated. 3785 If the protocol permits connections by unbound clients, and the peer is not bound, then the value 3786 stored in the object pointed to by address is unspecified. 3787 If the listen queue is empty of connection requests and O_NONBLOCK is not set on the file 3788 descriptor for the socket, accept( ) shall block until a connection is present. If the listen( ) queue is 3789 empty of connection requests and O_NONBLOCK is set on the file descriptor for the socket, 3790 accept( ) shall fail and set errno to [EAGAIN] or [EWOULDBLOCK]. 3791 The accepted socket cannot itself accept more connections. The original socket remains open and 3792 can accept more connections. 3793 RETURN VALUE 3794 Upon successful completion, accept( ) shall return the non-negative file descriptor of the accepted 3795 socket. Otherwise, -1 shall be returned and errno set to indicate the error. 3796 ERRORS 3797 The accept( ) function shall fail if: 3798 [EAGAIN] or [EWOULDBLOCK] 3799 O_NONBLOCK is set for the socket file descriptor and no connections are 3800 present to be accepted. 3801 [EBADF] The socket argument is not a valid file descriptor. 3802 [ECONNABORTED] 3803 A connection has been aborted. | 598 Technical Standard (2000) (Draft July 31, 2000) System Interfaces accept( ) 3804 [EINTR] The accept( ) function was interrupted by a signal that was caught before a 3805 valid connection arrived. 3806 [EINVAL] The socket is not accepting connections. 3807 [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. 3808 [ENFILE] The maximum number of file descriptors in the system are already open. 3809 [ENOTSOCK] The socket argument does not refer to a socket. 3810 [EOPNOTSUPP] The socket type of the specified socket does not support accepting 3811 connections. 3812 The accept( ) function may fail if: 3813 [ENOBUFS] No buffer space is available. 3814 [ENOMEM] There was insufficient memory available to complete the operation. | 3815 XSR [EPROTO] A protocol error has occurred; for example, the STREAMS protocol stack has 3816 not been initialized. 3817 EXAMPLES 3818 None. 3819 APPLICATION USAGE 3820 When a connection is available, select( ) indicates that the file descriptor for the socket is ready 3821 for reading. 3822 RATIONALE 3823 None. 3824 FUTURE DIRECTIONS 3825 None. 3826 SEE ALSO 3827 bind( ), connect( ), listen( ), socket( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 3828 3829 CHANGE HISTORY 3830 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. | 3831 The restrict keyword is added to the accept( ) prototype for alignment with the | 3832 ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 599 access( ) System Interfaces 3833 NAME 3834 access - determine accessibility of a file 3835 SYNOPSIS 3836 #include 3837 int access(const char *path, int amode); 3838 DESCRIPTION 3839 The access( ) function shall check the file named by the path name pointed to by the path 3840 argument for accessibility according to the bit pattern contained in amode, using the real user ID 3841 in place of the effective user ID and the real group ID in place of the effective group ID. 3842 The value of amode is either the bitwise-inclusive OR of the access permissions to be checked 3843 (R_OK, W_OK, X_OK) or the existence test (F_OK). 3844 If any access permissions are checked, each shall be checked individually, as described in the | 3845 Base Definitions volume of IEEE Std. 1003.1-200x, Chapter 3, Definitions. If the process has | 3846 appropriate privileges, an implementation may indicate success for X_OK even if none of the 3847 execute file permission bits are set. 3848 RETURN VALUE 3849 If the requested access is permitted, access( ) succeeds and shall return 0; otherwise, -1 shall be 3850 returned and errno shall be set to indicate the error. 3851 ERRORS 3852 The access( ) function shall fail if: 3853 [EACCES] Permission bits of the file mode do not permit the requested access, or search | 3854 permission is denied on a component of the path prefix. | 3855 [ELOOP] A loop exists in symbolic links encountered during resolution of the path | 3856 argument. | 3857 [ENAMETOOLONG] | 3858 The length of the path argument exceeds {PATH_MAX} or a path name | 3859 component is longer than {NAME_MAX}. | 3860 [ENOENT] A component of path does not name an existing file or path is an empty string. | 3861 [ENOTDIR] A component of the path prefix is not a directory. | 3862 [EROFS] Write access is requested for a file on a read-only file system. | 3863 The access( ) function may fail if: 3864 [EINVAL] The value of the amode argument is invalid. | 3865 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 3866 resolution of the path argument. | 3867 [ENAMETOOLONG] | 3868 As a result of encountering a symbolic link in resolution of the path argument, 3869 the length of the substituted path name string exceeded {PATH_MAX}. | 3870 [ETXTBSY] Write access is requested for a pure procedure (shared text) file that is being | 3871 executed. | 600 Technical Standard (2000) (Draft July 31, 2000) System Interfaces access( ) 3872 EXAMPLES 3873 Testing for the Existence of a File 3874 The following example tests whether a file named myfile exists in the /tmp directory. 3875 #include 3876 ... 3877 int result; 3878 const char *filename = "/tmp/myfile"; 3879 result = access (filename, F_OK); 3880 APPLICATION USAGE 3881 Additional values of amode other than the set defined in the description may be valid; for 3882 example, if a system has extended access controls. 3883 RATIONALE 3884 In early proposals, some inadequacies in the access( ) function led to the creation of an eaccess( ) 3885 function because: 3886 1. Historical implementations of access( ) do not test file access correctly when the process' 3887 real user ID is superuser. In particular, they always return zero when testing execute 3888 permissions without regard to whether the file is executable. 3889 2. The superuser has complete access to all files on a system. As a consequence, programs 3890 started by the superuser and switched to the effective user ID with lesser privileges cannot 3891 use access( ) to test their file access permissions. 3892 However, the historical model of eaccess( ) does not resolve problem (1), so this volume of 3893 IEEE Std. 1003.1-200x now allows access( ) to behave in the desired way because several 3894 implementations have corrected the problem. It was also argued that problem (2) is more easily 3895 solved by using open( ), chdir( ), or one of the exec functions as appropriate and responding to the 3896 error, rather than creating a new function that would not be as reliable. Therefore, eaccess( ) is not | 3897 included in this volume of IEEE Std. 1003.1-200x. | 3898 The sentence concerning appropriate privileges and execute permission bits reflects the two 3899 possibilities implemented by historical implementations when checking superuser access for 3900 X_OK. 3901 FUTURE DIRECTIONS 3902 None. 3903 SEE ALSO 3904 chmod( ), stat( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 3905 CHANGE HISTORY 3906 First released in Issue 1. Derived from Issue 1 of the SVID. | 3907 Issue 4 3908 The following change is incorporated for alignment with the ISO POSIX-1 standard: 3909 * The type of argument path is changed from char* to const char*. 3910 The following change is incorporated for alignment with the FIPS requirements: 3911 * In the ERRORS section, the condition whereby [ENAMETOOLONG] is returned if a path 3912 name component is larger that {NAME_MAX} is now defined as mandatory and marked as 3913 an extension. System Interfaces, Issue 6 601 access( ) System Interfaces 3914 Issue 4, Version 2 3915 The ERRORS section is updated for X/OPEN UNIX conformance as follows: 3916 * It states that [ELOOP] is returned if too many symbolic links are encountered during path 3917 name resolution. 3918 * A second [ENAMETOOLONG] condition is defined that may report excessive length of an 3919 intermediate result of path name resolution of a symbolic link. 3920 Issue 6 3921 The following changes are made for alignment with the ISO POSIX-1: 1996 standard: 3922 * The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. 3923 This is since behavior may vary from one file system to another. 3924 The following new requirements on POSIX implementations derive from alignment with the 3925 Single UNIX Specification: 3926 * The [ELOOP] mandatory error condition is added. 3927 * A second [ENAMETOOLONG] is added as an optional error condition. 3928 * The [ETXTBSY] optional error condition is added. 3929 The following changes were made to align with the IEEE P1003.1a draft standard: 3930 * The [ELOOP] optional error condition is added. 602 Technical Standard (2000) (Draft July 31, 2000) System Interfaces acos( ) 3931 NAME 3932 acos, acosf, acosl - arc cosine function | 3933 SYNOPSIS 3934 #include 3935 double acos(double x); 3936 float acosf(float x); | 3937 long double acosl(long double x); | 3938 DESCRIPTION | 3939 CX The functionality described on this reference page is aligned with the ISO C standard. Any 3940 conflict between the requirements described here and the ISO C standard is unintentional. This 3941 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 3942 The acos family of functions shall compute the principal value of the arc cosine of x. The value | 3943 of x should be in the range [-1,1]. 3944 An application wishing to check for error situations should set errno to 0 before calling acos( ). If 3945 errno is non-zero on return, or the value NaN is returned, an error has occurred. 3946 RETURN VALUE 3947 Upon successful completion, the acos family of functions shall return the arc cosine of x, in the | 3948 XSI range [0, ] radians. If the value of x is not in the range [-1,1], and is not ±Inf or NaN, either 0.0 or 3949 NaN shall be returnedand errno shall be set to [EDOM]. | 3950 XSI If x is NaN, NaN shall be returned and errno may be set to [EDOM]. If x is ±Inf, either 0.0 shall be 3951 returned and errno shall be set to [EDOM], or NaN shall be returned and errno may be set to 3952 [EDOM]. 3953 ERRORS 3954 The acos family of functions shall fail if: | 3955 XSI [EDOM] The value x is not ±Inf or NaN andis not in the range [-1,1]. | 3956 The acos family of functions may fail if: | 3957 XSI [EDOM] The value x is ±Inf or NaN. 3958 XSI No other errors shall occur. 3959 EXAMPLES 3960 None. 3961 APPLICATION USAGE 3962 None. 3963 RATIONALE 3964 None. 3965 FUTURE DIRECTIONS 3966 None. 3967 SEE ALSO 3968 cos( ), isnan( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 3969 CHANGE HISTORY 3970 First released in Issue 1. Derived from Issue 1 of the SVID. | System Interfaces, Issue 6 603 acos( ) System Interfaces 3971 Issue 4 3972 Removed references to matherr( ). 3973 The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 3974 ISO C standard and to rationalize error handling in the mathematics functions. 3975 The return value specified for [EDOM] is marked as an extension. 3976 Issue 5 3977 The DESCRIPTION is updated to indicate how an application should check for an error. This 3978 text was previously published in the APPLICATION USAGE section. | 3979 Issue 6 | 3980 The acosf( ) and acosl( ) functions are added for alignment with the ISO/IEC 9899: 1999 standard. | 604 Technical Standard (2000) (Draft July 31, 2000) System Interfaces acosh( ) 3981 NAME 3982 acosh, acoshf, acoshl, asinh, asinfh, asinfl, atanh, atanhf, atanhl - inverse hyperbolic functions | 3983 SYNOPSIS 3984 #include | 3985 double acosh(double x); 3986 float acoshf(float x); | 3987 long double acoshl(long double x); | 3988 double asinh(double x); | 3989 float asinhf(float x); | 3990 long double asinhl(long double x); | 3991 double atanh(double x); | 3992 float atanhf(float x); | 3993 long double atanhl(long double x); | 3994 DESCRIPTION | 3995 The acosh( ), asinh( ), and atanh( ) functions shall compute the inverse hyperbolic cosine, sine, and 3996 tangent of their argument, respectively. 3997 RETURN VALUE 3998 The acosh( ), asinh( ), and atanh( ) functions shall return the inverse hyperbolic cosine, sine, and 3999 tangent of their argument, respectively. 4000 The acosh( ), acoshf( ), and acoshl( ) functions shall return an implementation-defined value (NaN | 4001 or equivalent if available) and set errno to [EDOM] when its argument is less than 1.0. | 4002 The atanh( ), atanhf( ), and atanhl( ) functions shall return an implementation-defined value (NaN | 4003 or equivalent if available) and set errno to [EDOM] when its argument has absolute value greater | 4004 than 1.0. 4005 If x is NaN, the asinh( ), acosh( ), and atanh( ) functions shall return NaN and may set errno to 4006 [EDOM]. 4007 ERRORS 4008 The acosh( ), acoshf( ), and acoshl( ) functions shall fail if: | 4009 [EDOM] The x argument is less than 1.0. 4010 The atanh( ), atanhf( ), and atanhl( ) functions shall fail if: | 4011 [EDOM] The x argument has an absolute value greater than 1.0. 4012 The atanh( ), atanhf( ), and atanhl( ) functions shall fail if: | 4013 [ERANGE] The x argument has an absolute value equal to 1.0 | 4014 The asinh( ), acosh( ), and atanh( ) functions may fail if: 4015 [EDOM] The value of x is NaN. System Interfaces, Issue 6 605 acosh( ) System Interfaces 4016 EXAMPLES 4017 None. 4018 APPLICATION USAGE 4019 None. 4020 RATIONALE 4021 None. 4022 FUTURE DIRECTIONS 4023 None. 4024 SEE ALSO 4025 cosh( ), sinh( ), tanh( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 4026 CHANGE HISTORY 4027 First released in Issue 4, Version 2. 4028 Issue 5 4029 Moved from X/OPEN UNIX extension to BASE. | 4030 Issue 6 | 4031 The acoshf( ), acoshl( ), asinhf( ), asinhl( ), atanhf( ), and atanhl( ) functions are added for alignment | 4032 with the ISO/IEC 9899: 1999 standard. | 606 Technical Standard (2000) (Draft July 31, 2000) System Interfaces aio_cancel( ) 4033 NAME 4034 aio_cancel - cancel an asynchronous I/O request (REALTIME) 4035 SYNOPSIS 4036 AIO #include 4037 int aio_cancel(int fildes, struct aiocb *aiocbp); 4038 4039 DESCRIPTION 4040 The aio_cancel( ) function shall attempt to cancel one or more asynchronous I/O requests 4041 currently outstanding against file descriptor fildes. The aiocbp argument points to the 4042 asynchronous I/O control block for a particular request to be canceled. If aiocbp is NULL, then 4043 all outstanding cancelable asynchronous I/O requests against fildes shall be canceled. 4044 Normal asynchronous notification shall occur for asynchronous I/O operations that are 4045 successfully canceled. If there are requests that cannot be canceled, then the normal 4046 asynchronous completion process shall take place for those requests when they are completed. 4047 For requested operations that are successfully canceled, the associated error status shall be set to 4048 [ECANCELED] and the return status shall be -1. For requested operations that are not | 4049 successfully canceled, the aiocbp shall not be modified by aio_cancel( ). 4050 If aiocbp is not NULL, then if fildes does not have the same value as the file descriptor with which 4051 the asynchronous operation was initiated, unspecified results occur. 4052 Which operations are cancelable is implementation-defined. | 4053 RETURN VALUE 4054 The aio_cancel( ) function shall return the value AIO_CANCELED to the calling process if the 4055 requested operation(s) were canceled. The value AIO_NOTCANCELED shall be returned if at 4056 least one of the requested operation(s) cannot be canceled because it is in progress. In this case, 4057 the state of the other operations, if any, referenced in the call to aio_cancel( ) is not indicated by 4058 the return value of aio_cancel( ). The application may determine the state of affairs for these 4059 operations by using aio_error( ). The value AIO_ALLDONE is returned if all of the operations 4060 have already completed. Otherwise, the function shall return -1 and set errno to indicate the 4061 error. 4062 ERRORS 4063 The aio_cancel( ) function shall fail if: 4064 [EBADF] The fildes argument is not a valid file descriptor. | 4065 EXAMPLES 4066 None. 4067 APPLICATION USAGE 4068 The aio_cancel( ) function is part of the Asynchronous Input and Output option and need not be | 4069 available on all implementations. 4070 RATIONALE 4071 None. 4072 FUTURE DIRECTIONS 4073 None. System Interfaces, Issue 6 607 aio_cancel( ) System Interfaces 4074 SEE ALSO 4075 aio_read( ), aio_write( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 4076 CHANGE HISTORY 4077 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 4078 Issue 6 4079 The [ENOSYS] error condition has been removed as stubs need not be provided if an 4080 implementation does not support the Asynchronous Input and Output option. | 4081 The APPLICATION USAGE section is added. 608 Technical Standard (2000) (Draft July 31, 2000) System Interfaces aio_error( ) 4082 NAME 4083 aio_error - retrieve errors status for an asynchronous I/O operation (REALTIME) 4084 SYNOPSIS 4085 AIO #include 4086 int aio_error(const struct aiocb *aiocbp); 4087 4088 DESCRIPTION 4089 The aio_error( ) function shall return the error status associated with the aiocb structure 4090 referenced by the aiocbp argument. The error status for an asynchronous I/O operation is the 4091 SIO errno value that would be set by the corresponding read( ), write( ), fdatasync( ), or fsync( ) 4092 operation. If the operation has not yet completed, then the error status shall be equal to 4093 [EINPROGRESS]. | 4094 RETURN VALUE 4095 If the asynchronous I/O operation has completed successfully, then 0 shall be returned. If the 4096 asynchronous operation has completed unsuccessfully, then the error status, as described for 4097 SIO read( ), write( ), fdatasync( ), and fsync( ), shall be returned. If the asynchronous I/O operation has 4098 not yet completed, then [EINPROGRESS] shall be returned. 4099 ERRORS 4100 The aio_error( ) function may fail if: 4101 [EINVAL] The aiocbp argument does not refer to an asynchronous operation whose | 4102 return status has not yet been retrieved. 4103 EXAMPLES 4104 None. 4105 APPLICATION USAGE 4106 The aio_error( ) function is part of the Asynchronous Input and Output option and need not be | 4107 available on all implementations. 4108 RATIONALE 4109 None. 4110 FUTURE DIRECTIONS 4111 None. 4112 SEE ALSO 4113 aio_cancel( ), aio_fsync( ), aio_read( ), aio_return( ), aio_write( ), close( ), exec, exit( ), fork( ), lio_listio ( ), | 4114 lseek( ), read( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 4115 CHANGE HISTORY 4116 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 4117 Issue 6 4118 The [ENOSYS] error condition has been removed as stubs need not be provided if an 4119 implementation does not support the Asynchronous Input and Output option. | 4120 The APPLICATION USAGE section is added. System Interfaces, Issue 6 609 aio_fsync( ) System Interfaces 4121 NAME 4122 aio_fsync - asynchronous file synchronization (REALTIME) 4123 SYNOPSIS 4124 AIO #include 4125 int aio_fsync(int op, struct aiocb *aiocbp); 4126 4127 DESCRIPTION 4128 The aio_fsync( ) function asynchronously forces all I/O operations associated with the file 4129 indicated by the file descriptor aio_fildes member of the aiocb structure referenced by the aiocbp 4130 argument and queued at the time of the call to aio_fsync( ) to the synchronized I/O completion 4131 state. The function call shall return when the synchronization request has been initiated or 4132 queued to the file or device (even when the data cannot be synchronized immediately). 4133 If op is O_DSYNC, all currently queued I/O operations shall be completed as if by a call to 4134 fdatasync( ); that is, as defined for synchronized I/O data integrity completion. If op is O_SYNC, 4135 all currently queued I/O operations shall be completed as if by a call to fsync( ); that is, as 4136 defined for synchronized I/O file integrity completion. If the aio_fsync( ) function fails, or if the 4137 operation queued by aio_fsync( ) fails, then, as for fsync( ) and fdatasync( ), outstanding I/O 4138 operations are not guaranteed to have been completed. 4139 If aio_fsync( ) succeeds, then it is only the I/O that was queued at the time of the call to 4140 aio_fsync( ) that is guaranteed to be forced to the relevant completion state. The completion of 4141 subsequent I/O on the file descriptor is not guaranteed to be completed in a synchronized 4142 fashion. 4143 The aiocbp argument refers to an asynchronous I/O control block. The aiocbp value may be used 4144 as an argument to aio_error( ) and aio_return( ) in order to determine the error status and return 4145 status, respectively, of the asynchronous operation while it is proceeding. When the request is 4146 queued, the error status for the operation is [EINPROGRESS]. When all data has been | 4147 successfully transferred, the error status shall be reset to reflect the success or failure of the 4148 operation. If the operation does not complete successfully, the error status for the operation shall 4149 be set to indicate the error. The aio_sigevent member determines the asynchronous notification to 4150 occur as specified in Section 2.4.1 (on page 528) when all operations have achieved synchronized 4151 I/O completion. All other members of the structure referenced by aiocbp are ignored. If the 4152 control block referenced by aiocbp becomes an illegal address prior to asynchronous I/O 4153 completion, then the behavior is undefined. 4154 If the aio_fsync( ) function fails or the aiocbp indicates an error condition, data is not guaranteed 4155 to have been successfully transferred. 4156 RETURN VALUE 4157 The aio_fsync( ) function shall return the value 0 to the calling process if the I/O operation is 4158 successfully queued; otherwise, the function shall return the value -1 and set errno to indicate 4159 the error. 4160 ERRORS 4161 The aio_fsync( ) function shall fail if: 4162 [EAGAIN] The requested asynchronous operation was not queued due to temporary | 4163 resource limitations. 4164 [EBADF] The aio_fildes member of the aiocb structure referenced by the aiocbp argument | 4165 is not a valid file descriptor open for writing. 610 Technical Standard (2000) (Draft July 31, 2000) System Interfaces aio_fsync( ) 4166 [EINVAL] This implementation does not support synchronized I/O for this file. | 4167 [EINVAL] A value of op other than O_DSYNC or O_SYNC was specified. 4168 In the event that any of the queued I/O operations fail, aio_fsync( ) shall return the error 4169 condition defined for read( ) and write( ). The error is returned in the error status for the 4170 asynchronous fsync( ) operation, which can be retrieved using aio_error( ). 4171 EXAMPLES 4172 None. 4173 APPLICATION USAGE 4174 The aio_fsync( ) function is part of the Asynchronous Input and Output option and need not be | 4175 available on all implementations. 4176 RATIONALE 4177 None. 4178 FUTURE DIRECTIONS 4179 None. 4180 SEE ALSO 4181 fcntl( ), fdatasync( ), fsync( ), open( ), read( ), write( ), the Base Definitions volume of | 4182 IEEE Std. 1003.1-200x, | 4183 CHANGE HISTORY 4184 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 4185 Issue 6 4186 The [ENOSYS] error condition has been removed as stubs need not be provided if an 4187 implementation does not support the Asynchronous Input and Output option. | 4188 The APPLICATION USAGE section is added. System Interfaces, Issue 6 611 aio_read( ) System Interfaces 4189 NAME 4190 aio_read - asynchronous read from a file (REALTIME) 4191 SYNOPSIS 4192 AIO #include 4193 int aio_read(struct aiocb *aiocbp); 4194 4195 DESCRIPTION 4196 The aio_read( ) function allows the calling process to read aiocbp->aio_nbytes from the file | 4197 associated with aiocbp->aio_fildes into the buffer pointed to by aiocbp->aio_buf. The function call | 4198 shall return when the read request has been initiated or queued to the file or device (even when | 4199 the data cannot be delivered immediately). 4200 PIO If prioritized I/O is supported for this file, then the asynchronous operation is submitted at a 4201 priority equal to the scheduling priority of the process minus aiocbp->aio_reqprio. | 4202 The aiocbp value may be used as an argument to aio_error( ) and aio_return( ) in order to 4203 determine the error status and return status, respectively, of the asynchronous operation while it 4204 is proceeding. If an error condition is encountered during queuing, the function call shall return 4205 without having initiated or queued the request. The requested operation takes place at the 4206 absolute position in the file as given by aio_offset , as if lseek( ) were called immediately prior to 4207 the operation with an offset equal to aio_offset and a whence equal to {SEEK_SET}. After a 4208 successful call to enqueue an asynchronous I/O operation, the value of the file offset for the file 4209 is unspecified. 4210 The aiocbp->aio_lio_opcode field shall be ignored by aio_read( ). | 4211 The aiocbp argument points to an aiocb structure. If the buffer pointed to by aiocbp->aio_buf or | 4212 the control block pointed to by aiocbp becomes an illegal address prior to asynchronous I/O 4213 completion, then the behavior is undefined. 4214 Simultaneous asynchronous operations using the same aiocbp produce undefined results. 4215 SIO If synchronized I/O is enabled on the file associated with aiocbp->aio_fildes, the behavior of this | 4216 function shall be according to the definitions of synchronized I/O data integrity completion and | 4217 synchronized I/O file integrity completion. 4218 For any system action that changes the process memory space while an asynchronous I/O is 4219 outstanding to the address range being changed, the result of that action is undefined. 4220 For regular files, no data transfer shall occur past the offset maximum established in the open | 4221 file description associated with aiocbp->aio_fildes. | 4222 RETURN VALUE 4223 The aio_read( ) function shall return the value zero to the calling process if the I/O operation is 4224 successfully queued; otherwise, the function shall return the value -1 and set errno to indicate 4225 the error. 4226 ERRORS 4227 The aio_read( ) function shall fail if: 4228 [EAGAIN] The requested asynchronous I/O operation was not queued due to system | 4229 resource limitations. 4230 Each of the following conditions may be detected synchronously at the time of the call to 4231 aio_read( ), or asynchronously. If any of the conditions below are detected synchronously, the 4232 aio_read( ) function shall return -1 and set errno to the corresponding value. If any of the 4233 conditions below are detected asynchronously, the return status of the asynchronous operation 612 Technical Standard (2000) (Draft July 31, 2000) System Interfaces aio_read( ) 4234 is set to -1, and the error status of the asynchronous operation is set to the corresponding value. 4235 [EBADF] The aiocbp->aio_fildes argument is not a valid file descriptor open for reading. | 4236 [EINVAL] The file offset value implied by aiocbp->aio_offset would be invalid, aiocbp- | 4237 >aio_reqprio is not a valid value, or aiocbp->aio_nbytes is an invalid value. | 4238 In the case that the aio_read( ) successfully queues the I/O operation but the operation is 4239 subsequently canceled or encounters an error, the return status of the asynchronous operation is 4240 one of the values normally returned by the read( ) function call. In addition, the error status of 4241 the asynchronous operation is set to one of the error statuses normally set by the read( ) function 4242 call, or one of the following values: 4243 [EBADF] The aiocbp->aio_fildes argument is not a valid file descriptor open for reading. | 4244 [ECANCELED] The requested I/O was canceled before the I/O completed due to an explicit | 4245 aio_cancel( ) request. 4246 [EINVAL] The file offset value implied by aiocbp->aio_offset would be invalid. | 4247 The following condition may be detected synchronously or asynchronously: 4248 [EOVERFLOW] The file is a regular file, aiobcp->aio_nbytes is greater than 0, and the starting | 4249 offset in aiobcp->aio_offset is before the end-of-file and is at or beyond the offset | 4250 maximum in the open file description associated with aiocbp->aio_fildes. | 4251 EXAMPLES 4252 None. 4253 APPLICATION USAGE 4254 The aio_read( ) function is part of the Asynchronous Input and Output option and need not be | 4255 available on all implementations. 4256 RATIONALE 4257 None. 4258 FUTURE DIRECTIONS 4259 None. 4260 SEE ALSO 4261 aio_cancel( ), aio_error( ), lio_listio ( ), aio_return( ), aio_write( ), close( ), exec, exit( ), fork( ), lseek( ), | 4262 read( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 4263 CHANGE HISTORY 4264 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 4265 Large File Summit extensions are added. 4266 Issue 6 4267 The [ENOSYS] error condition has been removed as stubs need not be provided if an 4268 implementation does not support the Asynchronous Input and Output option. | 4269 The APPLICATION USAGE section is added. 4270 The following new requirements on POSIX implementations derive from alignment with the 4271 Single UNIX Specification: 4272 * In the DESCRIPTION, text is added to indicate setting of the offset maximum in the open file 4273 description. This change is to support large files. 4274 * In the ERRORS section, the [EOVERFLOW] condition is added. This change is to support 4275 large files. System Interfaces, Issue 6 613 aio_read( ) System Interfaces 614 Technical Standard (2000) (Draft July 31, 2000) System Interfaces aio_return( ) 4276 NAME 4277 aio_return - retrieve return status of an asynchronous I/O operation (REALTIME) 4278 SYNOPSIS 4279 AIO #include 4280 ssize_t aio_return(struct aiocb *aiocbp); 4281 4282 DESCRIPTION 4283 The aio_return( ) function shall return the return status associated with the aiocb structure 4284 referenced by the aiocbp argument. The return status for an asynchronous I/O operation is the 4285 value that would be returned by the corresponding read( ), write( ), or fsync( ) function call. If the 4286 error status for the operation is equal to [EINPROGRESS], then the return status for the | 4287 operation is undefined. The aio_return( ) function may be called exactly once to retrieve the 4288 return status of a given asynchronous operation; thereafter, if the same aiocb structure is used in 4289 a call to aio_return( ) or aio_error( ), an error may be returned. When the aiocb structure referred 4290 to by aiocbp is used to submit another asynchronous operation, then aio_return( ) may be 4291 successfully used to retrieve the return status of that operation. 4292 RETURN VALUE 4293 If the asynchronous I/O operation has completed, then the return status, as described for read( ), 4294 write( ), and fsync( ), shall be returned. If the asynchronous I/O operation has not yet completed, 4295 the results of aio_return( ) are undefined. 4296 ERRORS 4297 The aio_return( ) function may fail if: 4298 [EINVAL] The aiocbp argument does not refer to an asynchronous operation whose | 4299 return status has not yet been retrieved. 4300 EXAMPLES 4301 None. 4302 APPLICATION USAGE 4303 The aio_return( ) function is part of the Asynchronous Input and Output option and need not be | 4304 available on all implementations. 4305 RATIONALE 4306 None. 4307 FUTURE DIRECTIONS 4308 None. 4309 SEE ALSO 4310 aio_cancel( ), aio_error( ), aio_fsync( ), aio_read( ), aio_write( ), close( ), exec, exit( ), fork( ), lio_listio ( ), | 4311 lseek( ), read( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 4312 CHANGE HISTORY 4313 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 4314 Issue 6 4315 The [ENOSYS] error condition has been removed as stubs need not be provided if an 4316 implementation does not support the Asynchronous Input and Output option. | 4317 The APPLICATION USAGE section is added. 4318 The [EINVAL] error condition is updated as a ``may fail''. This is for consistency with the 4319 DESCRIPTION. System Interfaces, Issue 6 615 aio_suspend( ) System Interfaces 4320 NAME 4321 aio_suspend - wait for an asynchronous I/O request (REALTIME) 4322 SYNOPSIS 4323 AIO #include 4324 int aio_suspend(const struct aiocb * const list[], int nent, 4325 const struct timespec *timeout); 4326 4327 DESCRIPTION 4328 The aio_suspend( ) function shall suspend the calling thread until at least one of the asynchronous 4329 I/O operations referenced by the list argument has completed, until a signal interrupts the 4330 function, or, if timeout is not NULL, until the time interval specified by timeout has passed. If any 4331 of the aiocb structures in the list correspond to completed asynchronous I/O operations (that is, 4332 the error status for the operation is not equal to [EINPROGRESS]) at the time of the call, the | 4333 function shall return without suspending the calling thread. The list argument is an array of 4334 pointers to asynchronous I/O control blocks. The nent argument indicates the number of 4335 elements in the array. Each aiocb structure pointed to has been used in initiating an 4336 asynchronous I/O request via aio_read( ), aio_write( ), or lio_listio ( ). This array may contain 4337 NULL pointers, which are ignored. If this array contains pointers that refer to aiocb structures 4338 that have not been used in submitting asynchronous I/O, the effect is undefined. 4339 If the time interval indicated in the timespec structure pointed to by timeout passes before any of 4340 the I/O operations referenced by list are completed, then aio_suspend( ) shall return with an 4341 MON error. If the Monotonic Clock option is supported, the clock that shall be used to measure this 4342 time interval shall be the CLOCK_MONOTONIC clock. 4343 RETURN VALUE 4344 If the aio_suspend( ) function returns after one or more asynchronous I/O operations have 4345 completed, the function shall return zero. Otherwise, the function shall return a value of -1 and 4346 set errno to indicate the error. 4347 The application may determine which asynchronous I/O completed by scanning the associated 4348 error and return status using aio_error( ) and aio_return( ), respectively. 4349 ERRORS 4350 The aio_suspend( ) function shall fail if: 4351 [EAGAIN] No asynchronous I/O indicated in the list referenced by list completed in the | 4352 time interval indicated by timeout. 4353 [EINTR] A signal interrupted the aio_suspend( ) function. Note that, since each | 4354 asynchronous I/O operation may possibly provoke a signal when it 4355 completes, this error return may be caused by the completion of one (or more) 4356 of the very I/O operations being awaited. 4357 EXAMPLES 4358 None. 4359 APPLICATION USAGE 4360 The aio_suspend( ) function is part of the Asynchronous Input and Output option and need not | 4361 be available on all implementations. 4362 RATIONALE 4363 None. 616 Technical Standard (2000) (Draft July 31, 2000) System Interfaces aio_suspend( ) 4364 FUTURE DIRECTIONS 4365 None. 4366 SEE ALSO 4367 aio_read( ), aio_write( ), lio_listio ( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 4368 CHANGE HISTORY 4369 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 4370 Issue 6 4371 The [ENOSYS] error condition has been removed as stubs need not be provided if an 4372 implementation does not support the Asynchronous Input and Output option. | 4373 The APPLICATION USAGE section is added. 4374 The DESCRIPTION is updated for alignment with IEEE Std. 1003.1j-2000 by specifying that the 4375 CLOCK_MONOTONIC clock, if supported, is used. System Interfaces, Issue 6 617 aio_write( ) System Interfaces 4376 NAME 4377 aio_write - asynchronous write to a file (REALTIME) 4378 SYNOPSIS 4379 AIO #include 4380 int aio_write(struct aiocb *aiocbp); 4381 4382 DESCRIPTION 4383 The aio_write( ) function allows the calling process to write aiocbp->aio_nbytes to the file | 4384 associated with aiocbp->aio_fildes from the buffer pointed to by aiocbp->aio_buf. The function call | 4385 shall return when the write request has been initiated or, at a minimum, queued to the file or | 4386 device. 4387 PIO If prioritized I/O is supported for this file, then the asynchronous operation shall be submitted 4388 at a priority equal to the scheduling priority of the process minus aiocbp->aio_reqprio. | 4389 The aiocbp may be used as an argument to aio_error( ) and aio_return( ) in order to determine the 4390 error status and return status, respectively, of the asynchronous operation while it is proceeding. 4391 The aiocbp argument points to an aiocb structure. If the buffer pointed to by aiocbp->aio_buf or | 4392 the control block pointed to by aiocbp becomes an illegal address prior to asynchronous I/O 4393 completion, then the behavior is undefined. 4394 If O_APPEND is not set for the file descriptor aio_fildes , then the requested operation takes place 4395 at the absolute position in the file as given by aio_offset , as if lseek( ) were called immediately 4396 prior to the operation with an offset equal to aio_offset and a whence equal to {SEEK_SET}. If 4397 O_APPEND is set for the file descriptor, write operations append to the file in the same order as 4398 the calls were made. After a successful call to enqueue an asynchronous I/O operation, the value 4399 of the file offset for the file is unspecified. 4400 The aiocbp->aio_lio_opcode field shall be ignored by aio_write( ). | 4401 Simultaneous asynchronous operations using the same aiocbp produce undefined results. 4402 SIO If synchronized I/O is enabled on the file associated with aiocbp->aio_fildes, the behavior of this | 4403 function shall be according to the definitions of synchronized I/O data integrity completion, and | 4404 synchronized I/O file integrity completion. 4405 For any system action that changes the process memory space while an asynchronous I/O is 4406 outstanding to the address range being changed, the result of that action is undefined. 4407 For regular files, no data transfer shall occur past the offset maximum established in the open | 4408 file description associated with aiocbp->aio_fildes. | 4409 RETURN VALUE 4410 The aio_write( ) function shall return the value zero to the calling process if the I/O operation is 4411 successfully queued; otherwise, the function shall return the value -1 and set errno to indicate 4412 the error. 4413 ERRORS 4414 The aio_write( ) function shall fail if: 4415 [EAGAIN] The requested asynchronous I/O operation was not queued due to system | 4416 resource limitations. 4417 Each of the following conditions may be detected synchronously at the time of the call to 4418 aio_write( ), or asynchronously. If any of the conditions below are detected synchronously, the 4419 aio_write( ) function shall return -1 and set errno to the corresponding value. If any of the 618 Technical Standard (2000) (Draft July 31, 2000) System Interfaces aio_write( ) 4420 conditions below are detected asynchronously, the return status of the asynchronous operation 4421 shall be set to -1, and the error status of the asynchronous operation is set to the corresponding 4422 value. 4423 [EBADF] The aiocbp->aio_fildes argument is not a valid file descriptor open for writing. | 4424 [EINVAL] The file offset value implied by aiocbp->aio_offset would be invalid, aiocbp- | 4425 >aio_reqprio is not a valid value, or aiocbp->aio_nbytes is an invalid value. | 4426 In the case that the aio_write( ) successfully queues the I/O operation, the return status of the 4427 asynchronous operation shall be one of the values normally returned by the write( ) function call. 4428 If the operation is successfully queued but is subsequently canceled or encounters an error, the 4429 error status for the asynchronous operation contains one of the values normally set by the 4430 write( ) function call, or one of the following: 4431 [EBADF] The aiocbp->aio_fildes argument is not a valid file descriptor open for writing. | 4432 [EINVAL] The file offset value implied by aiocbp->aio_offset would be invalid. | 4433 [ECANCELED] The requested I/O was canceled before the I/O completed due to an explicit | 4434 aio_cancel( ) request. 4435 The following condition may be detected synchronously or asynchronously: | 4436 [EFBIG] The file is a regular file, aiobcp->aio_nbytes is greater than 0, and the starting | 4437 offset in aiobcp->aio_offset is at or beyond the offset maximum in the open file | 4438 description associated with aiocbp->aio_fildes. | 4439 EXAMPLES 4440 None. 4441 APPLICATION USAGE 4442 The aio_write( ) function is part of the Asynchronous Input and Output option and need not be | 4443 available on all implementations. 4444 RATIONALE 4445 None. 4446 FUTURE DIRECTIONS 4447 None. 4448 SEE ALSO 4449 aio_cancel( ), aio_error( ), aio_read( ), aio_return( ), close( ), exec, exit( ), fork( ), lio_listio ( ), lseek( ), | 4450 write( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 4451 CHANGE HISTORY 4452 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 4453 Large File Summit extensions are added. 4454 Issue 6 4455 The [ENOSYS] error condition has been removed as stubs need not be provided if an 4456 implementation does not support the Asynchronous Input and Output option. | 4457 The APPLICATION USAGE section is added. 4458 The following new requirements on POSIX implementations derive from alignment with the 4459 Single UNIX Specification: 4460 * In the DESCRIPTION, text is added to indicate that for regular files no data transfer occurs 4461 past the offset maximum established in the open file description associated with aiocbp- | 4462 >aio_fildes. | System Interfaces, Issue 6 619 aio_write( ) System Interfaces 4463 * The [EFBIG] error is added as part of the large file support extensions. 620 Technical Standard (2000) (Draft July 31, 2000) System Interfaces alarm( ) 4464 NAME 4465 alarm - schedule an alarm signal 4466 SYNOPSIS 4467 #include 4468 unsigned alarm(unsigned seconds); | 4469 DESCRIPTION | 4470 The alarm( ) function shall cause the system to generate a SIGALRM signal for the process after 4471 the number of realtime seconds specified by seconds have elapsed. Processor scheduling delays 4472 may prevent the process from handling the signal as soon as it is generated. 4473 If seconds is 0, a pending alarm request, if any, is canceled. 4474 Alarm requests are not stacked; only one SIGALRM generation can be scheduled in this manner. 4475 If the SIGALRM signal has not yet been generated, the call shall result in rescheduling the time 4476 at which the SIGALRM signal is generated. 4477 Interactions between alarm( ) and any of setitimer( ), ualarm( ), or usleep( ) are unspecified. | 4478 RETURN VALUE 4479 If there is a previous alarm( ) request with time remaining, alarm( ) shall return a non-zero value 4480 that is the number of seconds until the previous request would have generated a SIGALRM 4481 signal. Otherwise, alarm( ) shall return 0. 4482 ERRORS 4483 The alarm( ) function is always successful, and no return value is reserved to indicate an error. 4484 EXAMPLES 4485 None. 4486 APPLICATION USAGE 4487 The fork( ) function clears pending alarms in the child process. A new process image created by 4488 one of the exec functions inherits the time left to an alarm signal in the old process' image. 4489 Application writers should note that the type of the argument seconds and the return value of 4490 alarm( ) is unsigned. That means that a Strictly Conforming POSIX System Interfaces | 4491 Application cannot pass a value greater than the minimum guaranteed value for {UINT_MAX}, 4492 which the ISO C standard sets as 65 535, and any application passing a larger value is restricting 4493 its portability. A different type was considered, but historical implementations, including those 4494 with a 16-bit int type, consistently use either unsigned or int. | 4495 Application writers should be aware of possible interactions when the same process uses both 4496 the alarm( ) and sleep( ) functions. 4497 RATIONALE 4498 Many historical implementations (including Version 7 and System V) allow an alarm to occur up 4499 to a second early. Other implementations allow alarms up to half a second or one clock tick 4500 early or do not allow them to occur early at all. The latter is considered most appropriate, since it 4501 gives the most predictable behavior, especially since the signal can always be delayed for an 4502 indefinite amount of time due to scheduling. Applications can thus choose the seconds argument 4503 as the minimum amount of time they wish to have elapse before the signal. 4504 The term realtime here and elsewhere (sleep( ), times( )) is intended to mean ``wall clock'' time as 4505 common English usage, and has nothing to do with ``realtime operating systems''. It is in 4506 contrast to virtual time, which could be misinterpreted if just time were used. 4507 In some implementations, including 4.3 BSD, very large values of the seconds argument are | 4508 silently rounded down to an implementation-defined maximum value. This maximum is large | System Interfaces, Issue 6 621 alarm( ) System Interfaces 4509 enough (on the order of several months) that the effect is not noticeable. 4510 There were two possible choices for alarm generation in multi-threaded applications: generation 4511 for the calling thread or generation for the process. The first option would not have been 4512 particularly useful since the alarm state is maintained on a per-process basis and the alarm that 4513 is established by the last invocation of alarm( ) is the only one that would be active. 4514 Furthermore, allowing generation of an asynchronous signal for a thread would have introduced 4515 an exception to the overall signal model. This requires a compelling reason in order to be 4516 justified. 4517 FUTURE DIRECTIONS 4518 None. 4519 SEE ALSO 4520 alarm( ), exec, fork( ), getitimer( ), pause( ), sigaction( ), sleep( ), ualarm( ), usleep( ), the Base | 4521 Definitions volume of IEEE Std. 1003.1-200x, , | 4522 CHANGE HISTORY 4523 First released in Issue 1. Derived from Issue 1 of the SVID. | 4524 Issue 4 4525 The header is included in the SYNOPSIS section. 4526 Issue 4, Version 2 4527 The DESCRIPTION is updated to indicate that interactions with the setitimer( ), ualarm( ), and 4528 usleep( ) functions are unspecified. 4529 Issue 6 4530 The following new requirements on POSIX implementations derive from alignment with the 4531 Single UNIX Specification: 4532 * The DESCRIPTION is updated to indicate that interactions with the setitimer( ), ualarm( ), and 4533 usleep( ) functions are unspecified. 622 Technical Standard (2000) (Draft July 31, 2000) System Interfaces asctime( ) 4534 NAME 4535 asctime, asctime_r - convert date and time to a string 4536 SYNOPSIS 4537 #include 4538 char *asctime(const struct tm *timeptr); 4539 TSF char *asctime_r(const struct tm *restrict tm, char *restrict buf); | 4540 | 4541 DESCRIPTION 4542 CX The functionality described on this reference page is aligned with the ISO C standard. Any 4543 conflict between the requirements described here and the ISO C standard is unintentional. This 4544 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 4545 The asctime( ) function shall convert the broken-down time in the structure pointed to by timeptr 4546 into a string in the form: 4547 Sun Sep 16 01:03:52 1973\n\0 4548 using the equivalent of the following algorithm: 4549 char *asctime(const struct tm *timeptr) 4550 { 4551 static char wday_name[7][3] = { 4552 "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat" 4553 }; 4554 static char mon_name[12][3] = { 4555 "Jan", "Feb", "Mar", "Apr", "May", "Jun", 4556 "Jul", "Aug", "Sep", "Oct", "Nov", "Dec" 4557 }; 4558 static char result[26]; 4559 sprintf(result, "%.3s %.3s%3d %.2d:%.2d:%.2d %d\n", 4560 wday_name[timeptr->tm_wday], 4561 mon_name[timeptr->tm_mon], 4562 timeptr->tm_mday, timeptr->tm_hour, 4563 timeptr->tm_min, timeptr->tm_sec, 4564 1900 + timeptr->tm_year); 4565 return result; 4566 } 4567 The tm structure is defined in the header. 4568 CX The asctime( ), ctime( ), gmtime( ), and localtime( ) functions shall return values in one of two static 4569 objects: a broken-down time structure and an array of type char. Execution of any of the 4570 functions may overwrite the information returned in either of these objects by any of the other 4571 functions. 4572 The asctime( ) function need not be reentrant. A function that is not required to be reentrant is not 4573 required to be thread-safe. 4574 TSF The asctime_r( ) function shall convert the broken-down time in the structure pointed to by tm 4575 into a string (of the same form as that returned by asctime( )) that is placed in the user-supplied 4576 buffer pointed to by buf (which contains at least 26 bytes) and then return buf. System Interfaces, Issue 6 623 asctime( ) System Interfaces 4577 RETURN VALUE 4578 Upon successful completion, asctime( ) shall return a pointer to the string. 4579 TSF Upon successful completion, asctime_r( ) shall return a pointer to a character string containing 4580 the date and time. This string is pointed to by the argument buf. If the function is unsuccessful, 4581 it shall return NULL. 4582 ERRORS 4583 No errors are defined. 4584 EXAMPLES 4585 None. 4586 APPLICATION USAGE 4587 Values for the broken-down time structure can be obtained by calling gmtime( ) or localtime( ). 4588 This function is included for compatibility with older implementations, and does not support 4589 localized date and time formats. Applications should use strftime( ) to achieve maximum 4590 portability. 4591 The asctime_r( ) function is thread-safe and shall return values in a user-supplied buffer instead 4592 of possibly using a static data area that may be overwritten by each call. 4593 RATIONALE 4594 None. 4595 FUTURE DIRECTIONS 4596 None. 4597 SEE ALSO 4598 clock( ), ctime( ), difftime( ), gmtime( ), localtime( ), mktime( ), strftime( ), strptime( ), time( ), utime( ), | 4599 the Base Definitions volume of IEEE Std. 1003.1-200x, | 4600 CHANGE HISTORY 4601 First released in Issue 1. Derived from Issue 1 of the SVID. | 4602 Issue 4 4603 The location of the tm structure is now defined. 4604 The APPLICATION USAGE section is expanded to describe the time-handling functions 4605 generally and to refer users to strftime( ), which is a locale-dependent time-handling function. 4606 The following change is incorporated for alignment with the ISO C standard: 4607 * The type of argument timeptr is changed from struct tm* to const struct tm*. 4608 Issue 5 4609 Normative text previously in the APPLICATION USAGE section is moved to the 4610 DESCRIPTION. 4611 The asctime_r( ) function is included for alignment with the POSIX Threads Extension. 4612 A note indicating that the asctime( ) function need not be reentrant is added to the 4613 DESCRIPTION. 4614 Issue 6 4615 The asctime_r( ) function is marked as part of the Thread-Safe Functions option. | 4616 Extensions beyond the ISO C standard are now marked. 4617 The APPLICATION USAGE section is updated to include a note on the thread-safe function and 4618 its avoidance of possibly using a static data area. 624 Technical Standard (2000) (Draft July 31, 2000) System Interfaces asctime( ) 4619 The DESCRIPTION of asctime_r( ) is updated to describe the format of the string returned. | 4620 The restrict keyword is added to the asctime_r( ) prototype for alignment with the | 4621 ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 625 asin( ) System Interfaces 4622 NAME 4623 asin, asinf, asinl - arc sine function | 4624 SYNOPSIS 4625 #include 4626 double asin(double x); 4627 float asinf(float x); | 4628 long double asinl(long double x); | 4629 DESCRIPTION | 4630 CX The functionality described on this reference page is aligned with the ISO C standard. Any 4631 conflict between the requirements described here and the ISO C standard is unintentional. This 4632 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 4633 The asin( ), asinf( ), and asinl( ) functions shall compute the principal value of the arc sine of x. | 4634 The value of x should be in the range [-1,1]. 4635 An application wishing to check for error situations should set errno to 0, then call asin( ). If errno 4636 is non-zero on return, or the return value is NaN, an error has occurred. 4637 RETURN VALUE 4638 Upon successful completion, the asin( ), asinf( ), and asinl( ) functions shall return the arc sine of | 4639 XSI x, in the range [- /2, /2] radians. If the value of x is not in the range [-1,1], and is not ±Inf or 4640 NaN, either 0.0 or NaN shall be returned anderrno shall be set to [EDOM]. | 4641 XSI If x is NaN, NaN shall be returned and errno may be set to [EDOM]. 4642 If x is ±Inf, either 0.0 shall be returned and errno set to [EDOM], or NaN shall be returned and 4643 errno may be set to [EDOM]. 4644 If the result underflows, 0.0 shallbe returned and errno may be set to [ERANGE]. | 4645 ERRORS 4646 The asin( ), asinf( ), and asinl( ) functions shall fail if: | 4647 XSI [EDOM] The value x is not ±Inf or NaN andis not in the range [-1,1]. | 4648 The asin( ), asinf( ), and asinl( ) functions may fail if: | 4649 XSI [EDOM] The value of x is ±Inf or NaN. 4650 [ERANGE] The result underflows | 4651 XSI No other errors shall occur. 4652 EXAMPLES 4653 None. 4654 APPLICATION USAGE 4655 None. 4656 RATIONALE 4657 None. 4658 FUTURE DIRECTIONS 4659 None. 4660 SEE ALSO 4661 isnan( ), sin( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 626 Technical Standard (2000) (Draft July 31, 2000) System Interfaces asin( ) 4662 CHANGE HISTORY 4663 First released in Issue 1. Derived from Issue 1 of the SVID. | 4664 Issue 4 4665 References to matherr( ) are removed. 4666 The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 4667 ISO C standard and to rationalize error handling in the mathematics functions. 4668 The return value specified for [EDOM] is marked as an extension. 4669 Issue 5 4670 The DESCRIPTION is updated to indicate how an application should check for an error. This 4671 text was previously published in the APPLICATION USAGE section. | 4672 Issue 6 | 4673 The asinf( ) and asinl( ) functions are added for alignment with the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 627 asinh( ) System Interfaces 4674 NAME 4675 asinh - hyperbolic arc sine 4676 SYNOPSIS 4677 XSI #include 4678 double asinh(double x); 4679 4680 DESCRIPTION 4681 Refer to acosh( ). 628 Technical Standard (2000) (Draft July 31, 2000) System Interfaces assert( ) 4682 NAME 4683 assert - insert program diagnostics 4684 SYNOPSIS 4685 #include 4686 void assert(scalar expression); | 4687 DESCRIPTION | 4688 CX The functionality described on this reference page is aligned with the ISO C standard. Any 4689 conflict between the requirements described here and the ISO C standard is unintentional. This 4690 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 4691 The assert( ) macro inserts diagnostics into programs; it expands to a void expression. When it is | 4692 executed, if expression (which shall have a scalar type) is false (that is, compares equal to 0), | 4693 assert( ) shall write information about the particular call that failed on stderr and shall call abort( ). | 4694 The information written about the call that failed shall include the text of the argument, the | 4695 name of the source file, the source file line number, and the name of the enclosing function, the | 4696 latter are, respectively, the values of the preprocessing macros _ _FILE_ _ and _ _LINE_ _ and of | 4697 the identifier _ _func_ _. | 4698 Forcing a definition of the name NDEBUG, either from the compiler command line or with the | 4699 preprocessor control statement #define NDEBUG ahead of the #include statement, 4700 shall stop assertions from being compiled into the program. 4701 RETURN VALUE 4702 The assert( ) macro shall return no value. 4703 ERRORS 4704 No errors are defined. 4705 EXAMPLES 4706 None. 4707 APPLICATION USAGE 4708 None. 4709 RATIONALE 4710 None. 4711 FUTURE DIRECTIONS 4712 None. 4713 SEE ALSO 4714 abort( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , stderr | 4715 CHANGE HISTORY 4716 First released in Issue 1. Derived from Issue 1 of the SVID. | 4717 Issue 4 4718 The APPLICATION USAGE section is merged into the DESCRIPTION. | 4719 Issue 6 | 4720 The prototype for the expression argument to assert( ) is changed from int to scalar for alignment | 4721 with the ISO/IEC 9899: 1999 standard. | 4722 The DESCRIPTION of assert( ) is updated for alignment with the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 629 atan( ) System Interfaces 4723 NAME 4724 atan, atanf, atanl - arc tangent function | 4725 SYNOPSIS 4726 #include 4727 double atan(double x); 4728 float atanf(float x); | 4729 long double atanl(long double x); | 4730 DESCRIPTION | 4731 CX The functionality described on this reference page is aligned with the ISO C standard. Any 4732 conflict between the requirements described here and the ISO C standard is unintentional. This 4733 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 4734 The atan( ), atanf( ), and atanl( ) functions shall compute the principal value of the arc tangent of | 4735 x. 4736 An application wishing to check for error situations should set errno to 0 before calling atan( ). If 4737 errno is non-zero on return, or the return value is NaN, an error has occurred. 4738 RETURN VALUE 4739 Upon successful completion, the atan( ), atanf( ), and atanl( ) functions shall return the arc | 4740 tangent of x in the range [- /2, /2] radians. | 4741 XSI If x is NaN, NaN shall be returned and errno may be set to [EDOM]. | 4742 If the result underflows, 0.0 shall be returned and errno may be set to [ERANGE]. | 4743 ERRORS 4744 The atan( ), atanf( ), and atanl( ) functions may fail if: | 4745 XSI [EDOM] The value of x is NaN. 4746 [ERANGE] The result underflows | 4747 XSI No other errors shall occur. 4748 EXAMPLES 4749 None. 4750 APPLICATION USAGE 4751 None. 4752 RATIONALE 4753 None. 4754 FUTURE DIRECTIONS 4755 None. 4756 SEE ALSO 4757 atan2( ), isnan( ), tan( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 4758 CHANGE HISTORY 4759 First released in Issue 1. Derived from Issue 1 of the SVID. | 4760 Issue 4 4761 References to matherr( ) are removed. 4762 The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 4763 ISO C standard and to rationalize error handling in the mathematics functions. 630 Technical Standard (2000) (Draft July 31, 2000) System Interfaces atan( ) 4764 The return value specified for [EDOM] is marked as an extension. 4765 Issue 5 4766 The DESCRIPTION is updated to indicate how an application should check for an error. This 4767 text was previously published in the APPLICATION USAGE section. | 4768 Issue 6 | 4769 The atanf( ) and atanl( ) functions are added for alignment with the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 631 atan2( ) System Interfaces 4770 NAME 4771 atan2 - arc tangent function 4772 SYNOPSIS 4773 #include 4774 double atan2(double y, double x); 4775 float atan2f(float y, float x); | 4776 long double atan2l(long double y, long double x); | 4777 DESCRIPTION | 4778 CX The functionality described on this reference page is aligned with the ISO C standard. Any 4779 conflict between the requirements described here and the ISO C standard is unintentional. This 4780 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 4781 The atan2( ), atan2f( ), and atan2l( ) functions shall compute the principal value of the arc tangent | 4782 of y/x, using the signs of both arguments to determine the quadrant of the return value. | 4783 An application wishing to check for error situations should set errno to 0 before calling atan2( ). 4784 If errno is non-zero on return, or the return value is NaN, an error has occurred. 4785 RETURN VALUE 4786 Upon successful completion, the atan2( ), atan2f( ), and atan2l( ) functions shall return the arc | 4787 tangent of y/x in the range [- , ] radians. If both arguments are 0.0, an implementation-defined | 4788 value is returned and errno may be set to [EDOM]. | 4789 XSI If x or y is NaN, NaN shall be returned and errno may be set to [EDOM]. 4790 If the result underflows, 0.0 shall be returned and errno may be set to [ERANGE]. | 4791 ERRORS 4792 The atan2( ), atan2f( ), and atan2l( ) functions may fail if: | 4793 XSI [EDOM] Both arguments are 0.0 or one or more of the arguments is NaN. | 4794 [ERANGE] The result underflows | 4795 XSI No other errors shall occur. 4796 EXAMPLES 4797 None. 4798 APPLICATION USAGE 4799 None. 4800 RATIONALE 4801 None. 4802 FUTURE DIRECTIONS 4803 None. 4804 SEE ALSO 4805 atan( ), isnan( ), tan( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 4806 CHANGE HISTORY 4807 First released in Issue 1. Derived from Issue 1 of the SVID. | 4808 Issue 4 4809 References to matherr( ) are removed. 4810 The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 4811 ISO C standard and to rationalize error handling in the mathematics functions. 632 Technical Standard (2000) (Draft July 31, 2000) System Interfaces atan2( ) 4812 The return value specified for [EDOM] is marked as an extension. 4813 Issue 5 4814 The DESCRIPTION is updated to indicate how an application should check for an error. This 4815 text was previously published in the APPLICATION USAGE section. System Interfaces, Issue 6 633 atanh( ) System Interfaces 4816 NAME 4817 atanh - hyperbolic arc tangent 4818 SYNOPSIS 4819 XSI #include 4820 double atanh(double x); 4821 4822 DESCRIPTION 4823 Refer to acosh( ). 634 Technical Standard (2000) (Draft July 31, 2000) System Interfaces atexit( ) 4824 NAME 4825 atexit - register a function to run at process termination 4826 SYNOPSIS 4827 #include 4828 int atexit(void (*func)(void)); 4829 DESCRIPTION 4830 CX The functionality described on this reference page is aligned with the ISO C standard. Any 4831 conflict between the requirements described here and the ISO C standard is unintentional. This 4832 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 4833 The atexit( ) function registers the function pointed to by func, to be called without arguments at | 4834 normal program termination. At normal program termination, all functions registered by the | 4835 CX atexit( ) function shall be called, in the reverse order of their registration. Normal termination | 4836 occurs either by a call to exit( ) or a return from main( ). | 4837 At least 32 functions can be registered with atexit( ). 4838 CX After a successful call to any of the exec functions, any functions previously registered by atexit( ) 4839 shall no longer be registered. 4840 RETURN VALUE 4841 Upon successful completion, atexit( ) shall return 0; otherwise, it shall return a non-zero value. 4842 ERRORS 4843 No errors are defined. 4844 EXAMPLES 4845 None. 4846 APPLICATION USAGE 4847 The functions registered by a call to atexit( ) must return to ensure that all registered functions 4848 are called. 4849 The application should call sysconf( ) to obtain the value of {ATEXIT_MAX}, the number of 4850 functions that can be registered. There is no way for an application to tell how many functions 4851 have already been registered with atexit( ). 4852 RATIONALE 4853 None. 4854 FUTURE DIRECTIONS 4855 None. 4856 SEE ALSO 4857 exit( ), sysconf( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 4858 CHANGE HISTORY 4859 First released in Issue 4. Derived from the ANSI C standard. | 4860 Issue 4, Version 2 4861 The APPLICATION USAGE section is updated to indicate how an application can determine the 4862 setting of {ATEXIT_MAX}, which is a constant added for X/OPEN UNIX conformance. 4863 Issue 6 4864 Extensions beyond the ISO C standard are now marked. System Interfaces, Issue 6 635 atof( ) System Interfaces 4865 NAME 4866 atof - convert a string to double-precision number 4867 SYNOPSIS 4868 #include 4869 double atof(const char *str); 4870 DESCRIPTION 4871 CX The functionality described on this reference page is aligned with the ISO C standard. Any 4872 conflict between the requirements described here and the ISO C standard is unintentional. This 4873 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 4874 The call atof(str) shall be equivalent to: 4875 strtod(str,(char **)NULL), 4876 except that the handling of errors may differ. If the value cannot be represented, the behavior is 4877 undefined. 4878 RETURN VALUE 4879 The atof( ) function shall return the converted value if the value can be represented. 4880 ERRORS 4881 No errors are defined. 4882 EXAMPLES 4883 None. 4884 APPLICATION USAGE 4885 The atof( ) function is subsumed by strtod( ) but is retained because it is used extensively in 4886 existing code. If the number is not known to be in range, strtod( ) should be used because atof( ) is 4887 not required to perform any error checking. 4888 RATIONALE 4889 None. 4890 FUTURE DIRECTIONS 4891 None. 4892 SEE ALSO 4893 strtod( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 4894 CHANGE HISTORY 4895 First released in Issue 1. Derived from Issue 1 of the SVID. | 4896 Issue 4 4897 Reference to how str is converted is removed from the DESCRIPTION. 4898 The APPLICATION USAGE section is added. 4899 The following change is incorporated for alignment with the ISO C standard: 4900 * The type of argument str is changed from char* to const char*. 636 Technical Standard (2000) (Draft July 31, 2000) System Interfaces atoi( ) 4901 NAME 4902 atoi - convert a string to an integer 4903 SYNOPSIS 4904 #include 4905 int atoi(const char *str); 4906 DESCRIPTION 4907 CX The functionality described on this reference page is aligned with the ISO C standard. Any 4908 conflict between the requirements described here and the ISO C standard is unintentional. This 4909 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 4910 The call atoi(str) shall be equivalent to: 4911 (int) strtol(str, (char **)NULL, 10) 4912 except that the handling of errors may differ. If the value cannot be represented, the behavior is 4913 undefined. 4914 RETURN VALUE 4915 The atoi( ) function shall return the converted value if the value can be represented. 4916 ERRORS 4917 No errors are defined. 4918 EXAMPLES 4919 Converting an Argument 4920 The following example checks for proper usage of the program. If there is an argument and the 4921 decimal conversion of this argument (obtained using atoi( )) is greater than 0, then the program 4922 has a valid number of minutes to wait for an event. 4923 #include 4924 #include 4925 ... 4926 int minutes_to_event; 4927 ... 4928 if (argc < 2 || ((minutes_to_event = atoi (argv[1]))) <= 0) { 4929 fprintf(stderr, "Usage: %s minutes\n", argv[0]); exit(1); 4930 } 4931 ... 4932 APPLICATION USAGE 4933 The atoi( ) function is subsumed by strtol( ) but is retained because it is used extensively in 4934 existing code. If the number is not known to be in range, strtol( ) should be used because atoi( ) is 4935 not required to perform any error checking. 4936 RATIONALE 4937 None. 4938 FUTURE DIRECTIONS 4939 None. 4940 SEE ALSO 4941 strtol( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | System Interfaces, Issue 6 637 atoi( ) System Interfaces 4942 CHANGE HISTORY 4943 First released in Issue 1. Derived from Issue 1 of the SVID. | 4944 Issue 4 4945 Reference to how str is converted is removed from the DESCRIPTION. 4946 The APPLICATION USAGE section is added. 4947 The following change is incorporated for alignment with the ISO C standard: 4948 * The type of argument str is changed from char* to const char*. 638 Technical Standard (2000) (Draft July 31, 2000) System Interfaces atol( ) 4949 NAME 4950 atol, atoll - convert a string to a long integer | 4951 SYNOPSIS 4952 #include 4953 long atol(const char *str); | 4954 long long atoll(const char *nptr); | 4955 DESCRIPTION | 4956 CX The functionality described on this reference page is aligned with the ISO C standard. Any 4957 conflict between the requirements described here and the ISO C standard is unintentional. This 4958 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 4959 The call atol(str) shall be equivalent to: 4960 strtol(str, (char **)NULL, 10) 4961 The call atoll(str) shall be equivalent to: | 4962 strtoll(nptr, (char **)NULL, 10) | 4963 except that the handling of errors may differ. If the value cannot be represented, the behavior is | 4964 undefined. 4965 RETURN VALUE 4966 These functions shall return the converted value if the value can be represented. | 4967 ERRORS 4968 No errors are defined. 4969 EXAMPLES 4970 None. 4971 APPLICATION USAGE 4972 The atol( ) function is subsumed by strtol( ) but is retained because it is used extensively in 4973 existing code. If the number is not known to be in range, strtol( ) should be used because atol( ) is 4974 not required to perform any error checking. 4975 RATIONALE 4976 None. 4977 FUTURE DIRECTIONS 4978 None. 4979 SEE ALSO 4980 strtol( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 4981 CHANGE HISTORY 4982 First released in Issue 1. Derived from Issue 1 of the SVID. | 4983 Issue 4 4984 Reference to how str is converted is removed from the DESCRIPTION. 4985 The APPLICATION USAGE section is added. 4986 The following changes are incorporated for alignment with the ISO C standard: 4987 * The type of argument str is changed from char* to const char*. 4988 * The return type of the function is expanded to long. | System Interfaces, Issue 6 639 atol( ) System Interfaces 4989 Issue 6 | 4990 The atoll( ) function is added for alignment with the ISO/IEC 9899: 1999 standard. | 640 Technical Standard (2000) (Draft July 31, 2000) System Interfaces basename( ) 4991 NAME 4992 basename - return the last component of a path name | 4993 SYNOPSIS 4994 XSI #include 4995 char *basename(char *path); 4996 4997 DESCRIPTION 4998 The basename( ) function shall take the path name pointed to by path and return a pointer to the 4999 final component of the path name, deleting any trailing '/' characters. 5000 If the string consists entirely of the '/' character, basename( ) shall return a pointer to the string 5001 "/". If the string is exactly "//", it is implementation-defined whether '/' or "//" is | 5002 returned. | 5003 If path is a null pointer or points to an empty string, basename( ) shall return a pointer to the 5004 string ".". 5005 The basename( ) function may modify the string pointed to by path, and may return a pointer to 5006 static storage that may then be overwritten by a subsequent call to basename( ). 5007 The basename( ) function need not be reentrant. A function that is not required to be reentrant is 5008 not required to be thread-safe. 5009 RETURN VALUE 5010 The basename( ) function shall return a pointer to the final component of path. 5011 ERRORS 5012 No errors are defined. 5013 EXAMPLES 5014 Using basename( ) 5015 The following program fragment returns a pointer to the value lib, which is the base name of 5016 /usr/lib. 5017 #include 5018 ... 5019 char *name = "/usr/lib"; 5020 char *base; 5021 base = basename(name); 5022 ... 5023 Sample Input and Output Strings for basename( ) 5024 In the following table, the input string is the value pointed to by path, and the output string is 5025 the return value of the basename( ) function. ______________________________ 5026 _ Input String Output String _____________________________ 5027 "/usr/lib" "lib" 5028 "/usr/" "usr" 5029 _ "/" "/" _____________________________ System Interfaces, Issue 6 641 basename( ) System Interfaces 5030 APPLICATION USAGE 5031 None. 5032 RATIONALE 5033 None. 5034 FUTURE DIRECTIONS 5035 None. 5036 SEE ALSO 5037 dirname( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , the Shell and | 5038 Utilities volume of IEEE Std. 1003.1-200x, basename | 5039 CHANGE HISTORY 5040 First released in Issue 4, Version 2. 5041 Issue 5 5042 Moved from X/OPEN UNIX extension to BASE. 5043 Normative text previously in the APPLICATION USAGE section is moved to the 5044 DESCRIPTION. 5045 A note indicating that this function need not be reentrant is added to the DESCRIPTION. 5046 Issue 6 5047 In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. 642 Technical Standard (2000) (Draft July 31, 2000) System Interfaces bcmp( ) 5048 NAME 5049 bcmp - memory operations (LEGACY) 5050 SYNOPSIS 5051 XSI #include 5052 int bcmp(const void *s1, const void *s2, size_t n); 5053 5054 DESCRIPTION 5055 The bcmp( ) function shall compare the first n bytes of the area pointed to by s1 with the area 5056 pointed to by s2. 5057 RETURN VALUE 5058 The bcmp( ) function shall return 0 if s1 and s2 are identical; otherwise, it shall return non-zero. 5059 Both areas are assumed to be n bytes long. If the value of n is 0, bcmp( ) shall return 0. 5060 ERRORS 5061 No errors are defined. 5062 EXAMPLES 5063 None. 5064 APPLICATION USAGE 5065 memcmp( ) is preferred over this function. 5066 For maximum portability, it is recommended to replace the function call to bcmp( ) as follows: 5067 #define bcmp(b1,b2,len) memcmp((b1), (b2), (size_t)(len)) 5068 RATIONALE 5069 None. 5070 FUTURE DIRECTIONS 5071 This function may be withdrawn in a future version. 5072 SEE ALSO 5073 memcmp( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 5074 CHANGE HISTORY 5075 First released in Issue 4, Version 2. 5076 Issue 5 5077 Moved from X/OPEN UNIX extension to BASE. 5078 Issue 6 5079 This function is marked LEGACY. System Interfaces, Issue 6 643 bcopy( ) System Interfaces 5080 NAME 5081 bcopy - memory operations (LEGACY) 5082 SYNOPSIS 5083 XSI #include 5084 void bcopy(const void *s1, void *s2, size_t n); 5085 5086 DESCRIPTION 5087 The bcopy( ) function shall copy n bytes from the area pointed to by s1 to the area pointed to by 5088 s2. 5089 The bytes are copied correctly even if the area pointed to by s1 overlaps the area pointed to by 5090 s2. 5091 RETURN VALUE 5092 The bcopy( ) function shall return no value. 5093 ERRORS 5094 No errors are defined. 5095 EXAMPLES 5096 None. 5097 APPLICATION USAGE 5098 memmove( ) is preferred over this function. 5099 The following are approximately equivalent (note the order of the arguments): 5100 bcopy(s1,s2,n) = memmove(s2,s1,n) 5101 For maximum portability, it is recommended to replace the function call to bcopy( ) as follows: 5102 #define bcopy(b1,b2,len) (memmove((b2), (b1), (len)), (void) 0) 5103 RATIONALE 5104 None. 5105 FUTURE DIRECTIONS 5106 This function may be withdrawn in a future version. 5107 SEE ALSO 5108 memmove( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 5109 CHANGE HISTORY 5110 First released in Issue 4, Version 2. 5111 Issue 5 5112 Moved from X/OPEN UNIX extension to BASE. 5113 Issue 6 5114 This function is marked LEGACY. 644 Technical Standard (2000) (Draft July 31, 2000) System Interfaces bind( ) 5115 NAME 5116 bind - bind a name to a socket 5117 SYNOPSIS 5118 #include 5119 int bind(int socket, const struct sockaddr *address, 5120 socklen_t address_len); 5121 DESCRIPTION 5122 The bind( ) function shall assign a local socket address address to a socket identified by descriptor 5123 socket that has no local socket address assigned. Sockets created with the socket( ) function are 5124 initially unnamed; they are identified only by their address family. 5125 The bind( ) function takes the following arguments: 5126 socket Specifies the file descriptor of the socket to be bound. 5127 address Points to a sockaddr structure containing the address to be bound to the 5128 socket. The length and format of the address depend on the address family of 5129 the socket. 5130 address_len Specifies the length of the sockaddr structure pointed to by the address 5131 argument. 5132 The socket specified by socket may require the process to have appropriate privileges to use the | 5133 bind( ) function. 5134 RETURN VALUE 5135 Upon successful completion, bind( ) shall return 0; otherwise, -1 shall be returned and errno set 5136 to indicate the error. 5137 ERRORS 5138 The bind( ) function shall fail if: 5139 [EADDRINUSE] 5140 The specified address is already in use. 5141 [EADDRNOTAVAIL] 5142 The specified address is not available from the local machine. 5143 [EAFNOSUPPORT] 5144 The specified address is not a valid address for the address family of the 5145 specified socket. 5146 [EBADF] The socket argument is not a valid file descriptor. | 5147 [EINVAL] The socket is already bound to an address, and the protocol does not support 5148 binding to a new address; or the socket has been shut down. 5149 [ENOTSOCK] The socket argument does not refer to a socket. 5150 [EOPNOTSUPP] The socket type of the specified socket does not support binding to an 5151 address. 5152 If the address family of the socket is AF_UNIX, then bind( ) shall fail if: 5153 [EACCES] A component of the path prefix denies search permission, or the requested 5154 name requires writing in a directory with a mode that denies write 5155 permission. System Interfaces, Issue 6 645 bind( ) System Interfaces 5156 [EDESTADDRREQ] or [EISDIR] 5157 The address argument is a null pointer. 5158 [EIO] An I/O error occurred. 5159 [ELOOP] A loop exists in symbolic links encountered during resolution of the path | 5160 name in address. | 5161 [ENAMETOOLONG] 5162 A component of a path name exceeded {NAME_MAX} characters, or an entire 5163 path name exceeded {PATH_MAX} characters. 5164 [ENOENT] A component of the path name does not name an existing file or the path 5165 name is an empty string. 5166 [ENOTDIR] A component of the path prefix of the path name in address is not a directory. 5167 [EROFS] The name would reside on a read-only file system. 5168 The bind( ) function may fail if: 5169 [EACCES] The specified address is protected and the current user does not have 5170 permission to bind to it. 5171 [EINVAL] The address_len argument is not a valid length for the address family. 5172 [EISCONN] The socket is already connected. | 5173 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during | 5174 resolution of the path name in address. | 5175 [ENAMETOOLONG] 5176 Path name resolution of a symbolic link produced an intermediate result 5177 whose length exceeds {PATH_MAX}. 5178 [ENOBUFS] Insufficient resources were available to complete the call. | 5179 EXAMPLES 5180 None. 5181 APPLICATION USAGE 5182 An application program can retrieve the assigned socket name with the getsockname( ) function. 5183 RATIONALE 5184 None. 5185 FUTURE DIRECTIONS 5186 None. 5187 SEE ALSO 5188 connect( ), getsockname( ), listen( ), socket( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 5189 5190 CHANGE HISTORY 5191 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. | 646 Technical Standard (2000) (Draft July 31, 2000) System Interfaces bsd_signal( ) 5192 NAME 5193 bsd_signal - simplified signal facilities 5194 SYNOPSIS 5195 OB #include | 5196 void (*bsd_signal(int sig, void (*func)(int)))(int); 5197 5198 DESCRIPTION 5199 The bsd_signal( ) function provides a partially compatible interface for programs written to 5200 historical system interfaces (see APPLICATION USAGE). 5201 The function call bsd_signal(sig, func) has an effect as if implemented as: 5202 void (*bsd_signal(int sig, void (*func)(int)))(int) 5203 { 5204 struct sigaction act, oact; 5205 act.sa_handler = func; 5206 act.sa_flags = SA_RESTART; 5207 sigemptyset(&act.sa_mask); 5208 sigaddset(&act.sa_mask, sig); 5209 if (sigaction(sig, &act, &oact) == -1) 5210 return(SIG_ERR); 5211 return(oact.sa_handler); 5212 } 5213 The handler function should be declared: 5214 void handler(int sig); 5215 where sig is the signal number. The behavior is undefined if func is a function that takes more 5216 than one argument, or an argument of a different type. 5217 RETURN VALUE 5218 Upon successful completion, bsd_signal( ) shall return the previous action for sig. Otherwise, 5219 SIG_ERR shall be returned and errno shall be set to indicate the error. 5220 ERRORS 5221 Refer to sigaction( ). 5222 EXAMPLES 5223 None. 5224 APPLICATION USAGE 5225 This function is a direct replacement for the BSD signal( ) function for simple applications that 5226 are installing a single-argument signal handler function. If a BSD signal handler function is being 5227 installed that expects more than one argument, the application has to be modified to use 5228 sigaction( ). The bsd_signal( ) function differs from signal( ) in that the SA_RESTART flag is set 5229 and the SA_RESETHAND is clear when bsd_signal( ) is used. The state of these flags is not 5230 specified for signal( ). | 5231 It is recommended that new applications use the sigaction( ) function. | 5232 RATIONALE 5233 None. System Interfaces, Issue 6 647 bsd_signal( ) System Interfaces 5234 FUTURE DIRECTIONS 5235 None. 5236 SEE ALSO 5237 sigaction( ), sigaddset( ), sigemptyset( ), signal( ), the Base Definitions volume of | 5238 IEEE Std. 1003.1-200x, | 5239 CHANGE HISTORY 5240 First released in Issue 4, Version 2. 5241 Issue 5 5242 Moved from X/OPEN UNIX extension to BASE. | 5243 Issue 6 | 5244 This function is marked obsolescent. | 648 Technical Standard (2000) (Draft July 31, 2000) System Interfaces bsearch( ) 5245 NAME 5246 bsearch - binary search a sorted table 5247 SYNOPSIS 5248 #include 5249 void *bsearch(const void *key, const void *base, size_t nel, 5250 size_t width, int (*compar)(const void *, const void *)); 5251 DESCRIPTION 5252 CX The functionality described on this reference page is aligned with the ISO C standard. Any 5253 conflict between the requirements described here and the ISO C standard is unintentional. This 5254 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 5255 The bsearch( ) function searches an array of nel objects, the initial element of which is pointed to 5256 by base, for an element that matches the object pointed to by key. The size of each element in the 5257 array is specified by width. 5258 The comparison function pointed to by compar is called with two arguments that point to the key 5259 object and to an array element, in that order. 5260 The application shall ensure that the function returns an integer less than, equal to, or greater 5261 than 0 if the key object is considered, respectively, to be less than, to match, or to be greater than 5262 the array element. The application shall ensure that the array consists of all the elements that 5263 compare less than, all the elements that compare equal to, and all the elements that compare 5264 greater than the key object, in that order. 5265 RETURN VALUE 5266 The bsearch( ) function shall return a pointer to a matching member of the array, or a null pointer 5267 if no match is found. If two or more members compare equal, which member is returned is 5268 unspecified. 5269 ERRORS 5270 No errors are defined. 5271 EXAMPLES 5272 The example below searches a table containing pointers to nodes consisting of a string and its 5273 length. The table is ordered alphabetically on the string in the node pointed to by each entry. 5274 The code fragment below reads in strings and either finds the corresponding node and prints out 5275 the string and its length, or prints an error message. 5276 #include 5277 #include 5278 #include 5279 #define TABSIZE 1000 5280 struct node { /* These are stored in the table. */ 5281 char *string; 5282 int length; 5283 }; 5284 struct node table[TABSIZE]; /* Table to be searched. */ 5285 . 5286 . 5287 . 5288 { 5289 struct node *node_ptr, node; 5290 /* routine to compare 2 nodes */ System Interfaces, Issue 6 649 bsearch( ) System Interfaces 5291 int node_compare(const void *, const void *); 5292 char str_space[20]; /* Space to read string into. */ 5293 . 5294 . 5295 . 5296 node.string = str_space; 5297 while (scanf("%s", node.string) != EOF) { 5298 node_ptr = (struct node *)bsearch((void *)(&node), 5299 (void *)table, TABSIZE, 5300 sizeof(struct node), node_compare); 5301 if (node_ptr != NULL) { 5302 (void)printf("string = %20s, length = %d\n", 5303 node_ptr->string, node_ptr->length); 5304 } else { 5305 (void)printf("not found: %s\n", node.string); 5306 } 5307 } 5308 } 5309 /* 5310 This routine compares two nodes based on an 5311 alphabetical ordering of the string field. 5312 */ 5313 int 5314 node_compare(const void *node1, const void *node2) 5315 { 5316 return strcoll(((const struct node *)node1)->string, 5317 ((const struct node *)node2)->string); 5318 } 5319 APPLICATION USAGE 5320 The pointers to the key and the element at the base of the table should be of type pointer-to- 5321 element. 5322 The comparison function need not compare every byte, so arbitrary data may be contained in 5323 the elements in addition to the values being compared. 5324 In practice, the array is usually sorted according to the comparison function. 5325 RATIONALE 5326 None. 5327 FUTURE DIRECTIONS 5328 None. 5329 SEE ALSO 5330 hcreate( ), lsearch( ), qsort( ), tsearch( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 5331 5332 CHANGE HISTORY 5333 First released in Issue 1. Derived from Issue 1 of the SVID. | 5334 Issue 4 5335 Text indicating the need for various casts is removed from the APPLICATION USAGE section. 5336 The code in the EXAMPLES section is changed to use strcoll( ) instead of strcmp( ) in 5337 node_compare( ). 650 Technical Standard (2000) (Draft July 31, 2000) System Interfaces bsearch( ) 5338 The return value and the contents of the array are now requirements on the application. 5339 The DESCRIPTION is changed to specify the order of arguments. 5340 The following changes are incorporated for alignment with the ISO C standard: 5341 * The type of arguments key and base, and the type of arguments to compar, are changed from 5342 void* to const void*. 5343 * The requirement that the table be sorted according to compar is removed from the 5344 DESCRIPTION. 5345 Issue 6 5346 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 651 btowc( ) System Interfaces 5347 NAME 5348 btowc - single-byte to wide-character conversion 5349 SYNOPSIS 5350 #include 5351 #include 5352 wint_t btowc(int c); 5353 DESCRIPTION 5354 CX The functionality described on this reference page is aligned with the ISO C standard. Any 5355 conflict between the requirements described here and the ISO C standard is unintentional. This 5356 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 5357 The btowc( ) function shall determine whether c constitutes a valid (one-byte) character in the 5358 initial shift state. 5359 The behavior of this function shall be affected by the LC_CTYPE category of the current locale. 5360 RETURN VALUE 5361 The btowc( ) function shall return WEOF if c has the value EOF or if (unsigned char) c does not 5362 constitute a valid (one-byte) character in the initial shift state. Otherwise, it shall return the 5363 wide-character representation of that character. 5364 ERRORS 5365 No errors are defined. 5366 EXAMPLES 5367 None. 5368 APPLICATION USAGE 5369 None. 5370 RATIONALE 5371 None. 5372 FUTURE DIRECTIONS 5373 None. 5374 SEE ALSO 5375 wctob( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 5376 CHANGE HISTORY 5377 First released in Issue 5. Included for alignment with ISO/IEC 9899: 1990/Amendment 1: 1995 5378 (E). 652 Technical Standard (2000) (Draft July 31, 2000) System Interfaces bzero( ) 5379 NAME 5380 bzero - memory operations (LEGACY) 5381 SYNOPSIS 5382 XSI #include 5383 void bzero(void *s, size_t n); 5384 5385 DESCRIPTION 5386 The bzero( ) function shall place n zero-valued bytes in the area pointed to by s. 5387 RETURN VALUE 5388 The bzero( ) function shall return no value. 5389 ERRORS 5390 No errors are defined. 5391 EXAMPLES 5392 None. 5393 APPLICATION USAGE 5394 memset( ) is preferred over this function. 5395 For maximum portability, it is recommended to replace the function call to bzero( ) as follows: 5396 #define bzero(b,len) (memset((b), '\0', (len)), (void) 0) 5397 RATIONALE 5398 None. 5399 FUTURE DIRECTIONS 5400 This function may be withdrawn in a future version. 5401 SEE ALSO 5402 memset( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 5403 CHANGE HISTORY 5404 First released in Issue 4, Version 2. 5405 Issue 5 5406 Moved from X/OPEN UNIX extension to BASE. 5407 Issue 6 | 5408 This function is marked LEGACY. System Interfaces, Issue 6 653 cabs( ) System Interfaces 5409 NAME | 5410 cabs, cabsf, cabsl - return a complex absolute value | 5411 SYNOPSIS | 5412 #include | 5413 double cabs(double complex z); | 5414 float cabsf(float complex z); | 5415 long double cabsl(long double complex z); | 5416 DESCRIPTION | 5417 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 5418 conflict between the requirements described here and the ISO C standard is unintentional. This | 5419 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 5420 These functions shall compute the complex absolute value (also called norm, modulus, or | 5421 magnitude) of z. | 5422 RETURN VALUE | 5423 These functions shall return the complex absolute value. | 5424 ERRORS | 5425 No errors are defined. | 5426 EXAMPLES | 5427 None. | 5428 APPLICATION USAGE | 5429 None. | 5430 RATIONALE | 5431 None. | 5432 FUTURE DIRECTIONS | 5433 None. | 5434 SEE ALSO | 5435 The Base Definitions volume of IEEE Std. 1003.1-200x, | 5436 CHANGE HISTORY || 5437 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | 654 Technical Standard (2000) (Draft July 31, 2000) System Interfaces cacos( ) 5438 NAME | 5439 cacos, cacosf, cacosl - complex arc cosine functions | 5440 SYNOPSIS | 5441 #include | 5442 double complex cacos(double complex z); | 5443 float complex cacosf(float complex z); | 5444 long double complex cacosl(long double complex z); | 5445 DESCRIPTION | 5446 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 5447 conflict between the requirements described here and the ISO C standard is unintentional. This | 5448 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 5449 These functions shall compute the complex arc cosine of z, with branch cuts outside the interval | 5450 [-1, +1] along the real axis. | 5451 RETURN VALUE | 5452 These functions shall return the complex arc cosine value, in the range of a strip mathematically | 5453 unbounded along the imaginary axis and in the interval [0, ] along the real axis. | 5454 ERRORS | 5455 No errors are defined. | 5456 EXAMPLES | 5457 None. | 5458 APPLICATION USAGE | 5459 None. | 5460 RATIONALE | 5461 None. | 5462 FUTURE DIRECTIONS | 5463 None. | 5464 SEE ALSO | 5465 ccos( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 5466 CHANGE HISTORY || 5467 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 655 cacosh( ) System Interfaces 5468 NAME | 5469 cacosh, cacoshf, cacoshl - complex arc hyperbolic cosine functions | 5470 SYNOPSIS | 5471 #include | 5472 double complex cacosh(double complex z); | 5473 float complex cacoshf(float complex z); | 5474 long double complex cacoshl(long double complex z); | 5475 DESCRIPTION | 5476 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 5477 conflict between the requirements described here and the ISO C standard is unintentional. This | 5478 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 5479 These functions shall compute the complex arc hyperbolic cosine of z, with a branch cut at | 5480 values less than 1 along the real axis. | 5481 RETURN VALUE | 5482 These functions shall return the complex arc hyperbolic cosine value, in the range of a half-strip | 5483 of non-negative values along the real axis and in the interval [-i , +i ] along the imaginary axis. | 5484 ERRORS | 5485 No errors are defined. | 5486 EXAMPLES | 5487 None. | 5488 APPLICATION USAGE | 5489 None. | 5490 RATIONALE | 5491 None. | 5492 FUTURE DIRECTIONS | 5493 None. | 5494 SEE ALSO | 5495 ccosh( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 5496 CHANGE HISTORY || 5497 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | 656 Technical Standard (2000) (Draft July 31, 2000) System Interfaces calloc( ) 5498 NAME 5499 calloc - a memory allocator 5500 SYNOPSIS 5501 #include 5502 void *calloc(size_t nelem, size_t elsize); 5503 DESCRIPTION 5504 CX The functionality described on this reference page is aligned with the ISO C standard. Any 5505 conflict between the requirements described here and the ISO C standard is unintentional. This 5506 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 5507 The calloc( ) function allocates unused space for an array of nelem elements each of whose size in 5508 bytes is elsize. The space is initialized to all bits 0. 5509 The order and contiguity of storage allocated by successive calls to calloc( ) is unspecified. The 5510 pointer returned if the allocation succeeds is suitably aligned so that it may be assigned to a 5511 pointer to any type of object and then used to access such an object or an array of such objects in 5512 the space allocated (until the space is explicitly freed or reallocated). Each such allocation shall 5513 yield a pointer to an object disjoint from any other object. The pointer returned points to the start 5514 (lowest byte address) of the allocated space. If the space cannot be allocated, a null pointer is 5515 returned. If the size of the space requested is 0, the behavior is implementation-defined; the | 5516 value returned shall be either a null pointer or a unique pointer. 5517 RETURN VALUE 5518 Upon successful completion with both nelem and elsize non-zero, calloc( ) shall return a pointer to 5519 the allocated space. If either nelem or elsize is 0, then either a null pointer or a unique pointer 5520 value that can be successfully passed to free( ) shall be returned. Otherwise, it shall return a null 5521 CX pointer and set errno to indicate the error. 5522 ERRORS 5523 The calloc( ) function shall fail if: 5524 CX [ENOMEM] Insufficient memory is available. | 5525 EXAMPLES 5526 None. 5527 APPLICATION USAGE 5528 There is now no requirement for the implementation to support the inclusion of . 5529 RATIONALE 5530 None. 5531 FUTURE DIRECTIONS 5532 None. 5533 SEE ALSO 5534 free( ), malloc( ), realloc( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 5535 CHANGE HISTORY 5536 First released in Issue 1. Derived from Issue 1 of the SVID. | 5537 Issue 4 5538 The setting of errno and the [ENOMEM] error are marked as extensions. | 5539 The APPLICATION USAGE section is changed to record that need no longer be 5540 supported on XSI-conformant systems. System Interfaces, Issue 6 657 calloc( ) System Interfaces 5541 The following changes are incorporated in this issue for alignment with the ISO C standard: 5542 * The DESCRIPTION is updated to indicate: 5543 - The order and contiguity of storage allocated by successive calls to this function is 5544 unspecified. 5545 - Each allocation yields a pointer to an object disjoint from any other object. 5546 - The returned pointer points to the lowest byte address of the allocation. 5547 - The behavior if space is requested of zero size. 5548 * The RETURN VALUE section is updated to indicate what is returned if either nelem or elsize 5549 is 0. 5550 Issue 6 5551 Extensions beyond the ISO C standard are now marked. 5552 The following new requirements on POSIX implementations derive from alignment with the 5553 Single UNIX Specification: 5554 * The setting of errno and the [ENOMEM] error condition are mandatory if an insufficient | 5555 memory condition occurs. 658 Technical Standard (2000) (Draft July 31, 2000) System Interfaces carg( ) 5556 NAME | 5557 carg, cargf, cargl - complex argument functions | 5558 SYNOPSIS | 5559 #include | 5560 double carg(double complex z); | 5561 float cargf(float complex z); | 5562 long double cargl(long double complex z); | 5563 DESCRIPTION | 5564 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 5565 conflict between the requirements described here and the ISO C standard is unintentional. This | 5566 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 5567 These functions shall compute the argument (also called phase angle) of z, with a branch cut | 5568 along the negative real axis. | 5569 RETURN VALUE | 5570 These functions shall return the value of the argument in the interval [- , + ]. | 5571 ERRORS | 5572 No errors are defined. | 5573 EXAMPLES | 5574 None. | 5575 APPLICATION USAGE | 5576 None. | 5577 RATIONALE | 5578 None. | 5579 FUTURE DIRECTIONS | 5580 None. | 5581 SEE ALSO | 5582 cimag( ), conj( ), cproj( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 5583 CHANGE HISTORY || 5584 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 659 casin( ) System Interfaces 5585 NAME | 5586 casin, casinf, casinl - complex arc sine functions | 5587 SYNOPSIS | 5588 #include | 5589 double complex casin(double complex z); | 5590 float complex casinf(float complex z); | 5591 long double complex casinl(long double complex z); | 5592 DESCRIPTION | 5593 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 5594 conflict between the requirements described here and the ISO C standard is unintentional. This | 5595 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 5596 These functions shall compute the complex arc sine of z, with branch cuts outside the interval | 5597 [-1, +1] along the real axis. | 5598 RETURN VALUE | 5599 These functions shall return the complex arc sine value, in the range of a strip mathematically | 5600 unbounded along the imaginary axis and in the interval [- /2, + /2] along the real axis. | 5601 ERRORS | 5602 No errors are defined. | 5603 EXAMPLES | 5604 None. | 5605 APPLICATION USAGE | 5606 None. | 5607 RATIONALE | 5608 None. | 5609 FUTURE DIRECTIONS | 5610 None. | 5611 SEE ALSO | 5612 csin( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 5613 CHANGE HISTORY || 5614 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | 660 Technical Standard (2000) (Draft July 31, 2000) System Interfaces casinh( ) 5615 NAME | 5616 casinh, casinhf, casinhl - complex arc hyperbolic sine functions | 5617 SYNOPSIS | 5618 #include | 5619 double complex casinh(double complex z); | 5620 float complex casinhf(float complex z); | 5621 long double complex casinhl(long double complex z); | 5622 DESCRIPTION | 5623 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 5624 conflict between the requirements described here and the ISO C standard is unintentional. This | 5625 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 5626 These functions shall compute the complex arc hyperbolic sine of z, with branch cuts outside the | 5627 interval [-i, +i] along the imaginary axis. | 5628 RETURN VALUE | 5629 These functions shall return the complex arc hyperbolic sine value, in the range of a strip | 5630 mathematically unbounded along the real axis and in the interval [-i /2, +i /2] along the | 5631 imaginary axis. | 5632 ERRORS | 5633 No errors are defined. | 5634 EXAMPLES | 5635 None. | 5636 APPLICATION USAGE | 5637 None. | 5638 RATIONALE | 5639 None. | 5640 FUTURE DIRECTIONS | 5641 None. | 5642 SEE ALSO | 5643 csinh( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 5644 CHANGE HISTORY || 5645 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 661 catan( ) System Interfaces 5646 NAME | 5647 catan, catanf, catanl - complex arc tangent functions | 5648 SYNOPSIS | 5649 #include | 5650 double complex catan(double complex z); | 5651 float complex catanf(float complex z); | 5652 long double complex catanl(long double complex z); | 5653 DESCRIPTION | 5654 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 5655 conflict between the requirements described here and the ISO C standard is unintentional. This | 5656 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 5657 These functions shall compute the complex arc tangent of z, with branch cuts outside the | 5658 interval [-i, +i] along the imaginary axis. | 5659 RETURN VALUE | 5660 These functions shall return the complex arc tangent value, in the range of a strip | 5661 mathematically unbounded along the imaginary axis and in the interval [- /2, + /2] along the | 5662 real axis. | 5663 ERRORS | 5664 No errors are defined. | 5665 EXAMPLES | 5666 None. | 5667 APPLICATION USAGE | 5668 None. | 5669 RATIONALE | 5670 None. | 5671 FUTURE DIRECTIONS | 5672 None. | 5673 SEE ALSO | 5674 ctan( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 5675 CHANGE HISTORY || 5676 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | 662 Technical Standard (2000) (Draft July 31, 2000) System Interfaces catanh( ) 5677 NAME | 5678 catanh, catanhf, catanhl - complex arc hyperbolic tangent functions | 5679 SYNOPSIS | 5680 #include | 5681 double complex catanh(double complex z); | 5682 float complex catanhf(float complex z); | 5683 long double complex catanhl(long double complex z); | 5684 DESCRIPTION | 5685 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 5686 conflict between the requirements described here and the ISO C standard is unintentional. This | 5687 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 5688 These functions shall compute the complex arc hyperbolic tangent of z, with branch cuts outside | 5689 the interval [-1, +1] along the real axis. | 5690 RETURN VALUE | 5691 These functions shall return the complex arc hyperbolic tangent value, in the range of a strip | 5692 mathematically unbounded along the real axis and in the interval [-i /2, +i /2] along the | 5693 imaginary axis. | 5694 ERRORS | 5695 No errors are defined. | 5696 EXAMPLES | 5697 None. | 5698 APPLICATION USAGE | 5699 None. | 5700 RATIONALE | 5701 None. | 5702 FUTURE DIRECTIONS | 5703 None. | 5704 SEE ALSO | 5705 ctanh( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 5706 CHANGE HISTORY || 5707 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 663 catclose( ) System Interfaces 5708 NAME 5709 catclose - close a message catalog descriptor 5710 SYNOPSIS 5711 XSI #include 5712 int catclose(nl_catd catd); 5713 5714 DESCRIPTION 5715 The catclose( ) function shall close the message catalog identified by catd. If a file descriptor is 5716 used to implement the type nl_catd, that file descriptor shall be closed. 5717 RETURN VALUE 5718 Upon successful completion, catclose( ) shall return 0; otherwise, -1 shall be returned, and errno 5719 set to indicate the error. 5720 ERRORS 5721 The catclose( ) function may fail if: 5722 [EBADF] The catalog descriptor is not valid. | 5723 [EINTR] The catclose( ) function was interrupted by a signal. | 5724 EXAMPLES 5725 None. 5726 APPLICATION USAGE 5727 None. 5728 RATIONALE 5729 None. 5730 FUTURE DIRECTIONS 5731 None. 5732 SEE ALSO 5733 catgets( ), catopen( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 5734 CHANGE HISTORY 5735 First released in Issue 2. 5736 Issue 4 5737 The [EBADF] and [EINTR] errors are added to the ERRORS section. 664 Technical Standard (2000) (Draft July 31, 2000) System Interfaces catgets( ) 5738 NAME 5739 catgets - read a program message 5740 SYNOPSIS 5741 XSI #include 5742 char *catgets(nl_catd catd, int set_id, int msg_id, const char *s); 5743 5744 DESCRIPTION 5745 The catgets( ) function attempts to read message msg_id, in set set_id, from the message catalog 5746 identified by catd. The catd argument is a message catalog descriptor returned from an earlier 5747 call to catopen( ). The s argument points to a default message string which shall be returned by 5748 catgets( ) if it cannot retrieve the identified message. 5749 The catgets( ) function need not be reentrant. A function that is not required to be reentrant is not 5750 required to be thread-safe. 5751 RETURN VALUE 5752 If the identified message is retrieved successfully, catgets( ) shall return a pointer to an internal 5753 buffer area containing the null-terminated message string. If the call is unsuccessful for any 5754 reason, s shall be returned and errno may be set to indicate the error. 5755 ERRORS 5756 The catgets( ) function may fail if: 5757 [EBADF] The catd argument is not a valid message catalog descriptor open for reading. | 5758 [EINTR] The read operation was terminated due to the receipt of a signal, and no data | 5759 was transferred. 5760 [EINVAL] The message catalog identified by catd is corrupted. | 5761 [ENOMSG] The message identified by set_id and msg_id is not in the message catalog. | 5762 EXAMPLES 5763 None. 5764 APPLICATION USAGE 5765 None. 5766 RATIONALE 5767 None. 5768 FUTURE DIRECTIONS 5769 None. 5770 SEE ALSO 5771 catclose( ), catopen( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 5772 CHANGE HISTORY 5773 First released in Issue 2. 5774 Issue 4 5775 The type of argument s is changed from char* to const char*. 5776 The [EBADF] and [EINTR] errors are added to the ERRORS section. System Interfaces, Issue 6 665 catgets( ) System Interfaces 5777 Issue 4, Version 2 5778 The following changes are incorporated for X/OPEN UNIX conformance: 5779 * The RETURN VALUE section notes that errno may be set to indicate an error. 5780 * In the ERRORS section, [EINVAL] and [ENOMSG] are added as optional errors. 5781 Issue 5 5782 A note indicating that this function need not be reentrant is added to the DESCRIPTION. 5783 Issue 6 5784 In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. 666 Technical Standard (2000) (Draft July 31, 2000) System Interfaces catopen( ) 5785 NAME 5786 catopen - open a message catalog 5787 SYNOPSIS 5788 XSI #include 5789 nl_catd catopen(const char *name, int oflag); 5790 5791 DESCRIPTION 5792 The catopen( ) function shall open a message catalog and return a message catalog descriptor. 5793 The name argument specifies the name of the message catalog to be opened. If name contains a 5794 '/', then name specifies a complete name for the message catalog. Otherwise, the environment 5795 variable NLSPATH is used with name substituted for %N (see the Base Definitions volume of | 5796 IEEE Std. 1003.1-200x, Chapter 8, Environment Variables). If NLSPATH does not exist in the | 5797 environment, or if a message catalog cannot be found in any of the components specified by 5798 NLSPATH, then an implementation-defined default path is used. This default may be affected by | 5799 the setting of LC_MESSAGES if the value of oflag is NL_CAT_LOCALE, or the LANG 5800 environment variable if oflag is 0. 5801 A message catalog descriptor remains valid in a process until that process closes it, or a 5802 successful call to one of the exec functions. A change in the setting of the LC_MESSAGES 5803 category may invalidate existing open catalogs. 5804 If a file descriptor is used to implement message catalog descriptors, the FD_CLOEXEC flag 5805 shall be set; see . 5806 If the value of the oflag argument is 0, the LANG environment variable is used to locate the 5807 catalog without regard to the LC_MESSAGES category. If the oflag argument is 5808 NL_CAT_LOCALE, the LC_MESSAGES category is used to locate the message catalog (see the | 5809 Base Definitions volume of IEEE Std. 1003.1-200x, Section 8.2, Internationalization Variables). | 5810 RETURN VALUE 5811 Upon successful completion, catopen( ) shall return a message catalog descriptor for use on 5812 subsequent calls to catgets( ) and catclose( ). Otherwise, catopen( ) shall return (nl_catd) -1 and set 5813 errno to indicate the error. 5814 ERRORS 5815 The catopen( ) function may fail if: 5816 [EACCES] Search permission is denied for the component of the path prefix of the | 5817 message catalog or read permission is denied for the message catalog. 5818 [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. | 5819 [ENAMETOOLONG] | 5820 The length of a path name of the message catalog exceeds {PATH_MAX} or a | 5821 path name component is longer than {NAME_MAX}. | 5822 [ENAMETOOLONG] 5823 Path name resolution of a symbolic link produced an intermediate result 5824 whose length exceeds {PATH_MAX}. 5825 [ENFILE] Too many files are currently open in the system. | 5826 [ENOENT] The message catalog does not exist or the name argument points to an empty | 5827 string. 5828 [ENOMEM] Insufficient storage space is available. | System Interfaces, Issue 6 667 catopen( ) System Interfaces 5829 [ENOTDIR] A component of the path prefix of the message catalog is not a directory. | 5830 EXAMPLES 5831 None. 5832 APPLICATION USAGE 5833 Some implementations of catopen( ) use malloc( ) to allocate space for internal buffer areas. The 5834 catopen( ) function may fail if there is insufficient storage space available to accommodate these 5835 buffers. 5836 Portable applications must assume that message catalog descriptors are not valid after a call to 5837 one of the exec functions. 5838 Application writers should be aware that guidelines for the location of message catalogs have 5839 not yet been developed. Therefore they should take care to avoid conflicting with catalogs used 5840 by other applications and the standard utilities. 5841 RATIONALE 5842 None. 5843 FUTURE DIRECTIONS 5844 None. 5845 SEE ALSO 5846 catclose( ), catgets( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , | 5847 , the Shell and Utilities volume of IEEE Std. 1003.1-200x | 5848 CHANGE HISTORY 5849 First released in Issue 2. 5850 Issue 4 5851 The type of argument name is changed from char* to const char*. 5852 The DESCRIPTION is updated: 5853 * To indicate the longevity of message catalog descriptors. 5854 * To specify values for the oflag argument and the effect of LC_MESSAGES and NLSPATH. 5855 The [EACCES], [EMFILE], [ENAMETOOLONG], [ENFILE], [ENOENT], and [ENOTDIR] errors | 5856 are added to the ERRORS section. | 5857 The APPLICATION USAGE section is updated to indicate: 5858 * Portable applications should not assume the continued validity of message catalog 5859 descriptors after a call to one of the exec functions. 5860 * Message catalogs must be located with care. 5861 Issue 4, Version 2 5862 The following change is incorporated for X/OPEN UNIX conformance: 5863 * In the ERRORS section, an [ENAMETOOLONG] condition is defined that may report 5864 excessive length of an intermediate result of path name resolution of a symbolic link. 668 Technical Standard (2000) (Draft July 31, 2000) System Interfaces cbrt( ) 5865 NAME 5866 cbrt, cbrtf, cbrtl - cube root functions | 5867 SYNOPSIS 5868 #include | 5869 double cbrt(double x); 5870 float cbrtf(float x); | 5871 long double cbrtl(long double x); | 5872 DESCRIPTION | 5873 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 5874 conflict between the requirements described here and the ISO C standard is unintentional. This | 5875 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 5876 These functions shall compute the real cube root of x. | 5877 An application wishing to check for error situations should set errno to 0 before calling these | 5878 functions. If errno is non-zero on return, or the return value is NaN, an error has occurred. | 5879 RETURN VALUE 5880 Upon successful completion, these functions shall return the cube root of x. | 5881 If x is ±Inf, these functions shall return x. | 5882 If x is NaN, NaN shall be returned and errno may be set to [EDOM]. | 5883 ERRORS 5884 These functions may fail if: | 5885 [EDOM] The value of x is NaN. 5886 EXAMPLES 5887 None. 5888 APPLICATION USAGE 5889 None. 5890 RATIONALE 5891 For some applications, a true cube root function, which returns negative results for negative | 5892 arguments, is more appropriate than pow(x, 1.0/3.0), which returns a NaN for x less than 0. | 5893 FUTURE DIRECTIONS 5894 None. 5895 SEE ALSO 5896 The Base Definitions volume of IEEE Std. 1003.1-200x, | 5897 CHANGE HISTORY 5898 First released in Issue 4, Version 2. 5899 Issue 5 5900 Moved from X/OPEN UNIX extension to BASE. | 5901 Issue 6 | 5902 The cbrt( ) function is no longer marked XSI. || 5903 The cbrtf( ) and cbrtl( ) functions are added for alignment with the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 669 ccos( ) System Interfaces 5904 NAME | 5905 ccos, ccosf, ccosl - complex cosine functions | 5906 SYNOPSIS | 5907 #include | 5908 double complex ccos(double complex z); | 5909 float complex ccosf(float complex z); | 5910 long double complex ccosl(long double complex z); | 5911 DESCRIPTION | 5912 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 5913 conflict between the requirements described here and the ISO C standard is unintentional. This | 5914 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 5915 These functions shall compute the complex cosine of z. | 5916 RETURN VALUE | 5917 These functions shall return the complex cosine value. | 5918 ERRORS | 5919 No errors are defined. | 5920 EXAMPLES | 5921 None. | 5922 APPLICATION USAGE | 5923 None. | 5924 RATIONALE | 5925 None. | 5926 FUTURE DIRECTIONS | 5927 None. | 5928 SEE ALSO | 5929 cacos( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 5930 CHANGE HISTORY || 5931 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | 670 Technical Standard (2000) (Draft July 31, 2000) System Interfaces ccosh( ) 5932 NAME | 5933 ccosh, ccoshf, ccoshl - complex hyperbolic cosine functions | 5934 SYNOPSIS | 5935 #include | 5936 double complex ccosh(double complex z); | 5937 float complex ccoshf(float complex z); | 5938 long double complex ccoshl(long double complex z); | 5939 DESCRIPTION | 5940 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 5941 conflict between the requirements described here and the ISO C standard is unintentional. This | 5942 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 5943 These functions shall compute the complex hyperbolic cosine of z. | 5944 RETURN VALUE | 5945 These functions shall return the complex hyperbolic cosine value. | 5946 ERRORS | 5947 No errors are defined. | 5948 EXAMPLES | 5949 None. | 5950 APPLICATION USAGE | 5951 None. | 5952 RATIONALE | 5953 None. | 5954 FUTURE DIRECTIONS | 5955 None. | 5956 SEE ALSO | 5957 cacosh( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 5958 CHANGE HISTORY || 5959 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 671 ceil( ) System Interfaces 5960 NAME 5961 ceil, ceilf, ceill - ceiling value function | 5962 SYNOPSIS 5963 #include 5964 double ceil(double x); 5965 float ceilf(float x); | 5966 long double ceill(long double x); | 5967 DESCRIPTION | 5968 CX The functionality described on this reference page is aligned with the ISO C standard. Any 5969 conflict between the requirements described here and the ISO C standard is unintentional. This 5970 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 5971 The ceil( ), ceilf( ), and ceill( ) functions shall compute the smallest integral value not less than x. | 5972 An application wishing to check for error situations should set errno to 0 before calling ceil( ). If 5973 errno is non-zero on return, or the return value is NaN, an error has occurred. 5974 RETURN VALUE 5975 Upon successful completion, the ceil( ), ceilf( ), and ceill( ) functions shall return the smallest | 5976 integral value not less than x, expressed as a type double. | 5977 XSI If x is NaN, NaN shall be returned and errno may be set to [EDOM]. | 5978 If the correct value would cause overflow, HUGE_VAL shall be returned and errno set to 5979 XSI [ERANGE]. If x is ±Inf or ±0, the value of x shall be returned. | 5980 ERRORS 5981 The ceil( ), ceilf( ), and ceill( ) functions shall fail if: | 5982 [ERANGE] The result overflows. | 5983 The ceil( ), ceilf( ), and ceill( ) functions may fail if: | 5984 XSI [EDOM] The value of x is NaN. 5985 XSI No other errors shall occur. 5986 EXAMPLES 5987 None. 5988 APPLICATION USAGE 5989 The integral value returned by ceil( ) as a double need not be expressible as an int or long. The | 5990 return value should be tested before assigning it to an integer type to avoid the undefined results 5991 of an integer overflow. 5992 The ceil( ) function can only overflow when the floating point representation has 5993 DBL_MANT_DIG > DBL_MAX_EXP. 5994 RATIONALE 5995 None. 5996 FUTURE DIRECTIONS 5997 None. 5998 SEE ALSO 5999 floor( ), isnan( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 672 Technical Standard (2000) (Draft July 31, 2000) System Interfaces ceil( ) 6000 CHANGE HISTORY 6001 First released in Issue 1. Derived from Issue 1 of the SVID. | 6002 Issue 4 6003 References to matherr( ) are removed. 6004 The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 6005 ISO C standard and to rationalize error handling in the mathematics functions. 6006 The return value specified for [EDOM] is marked as an extension. | 6007 Support for x being ±Inf or ±0 is added to the RETURN VALUE section and marked as an 6008 extension. 6009 Issue 5 6010 The DESCRIPTION is updated to indicate how an application should check for an error. This 6011 text was previously published in the APPLICATION USAGE section. | 6012 Issue 6 || 6013 The ceilf( ) and ceill( ) functions are added for alignment with the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 673 cexp( ) System Interfaces 6014 NAME | 6015 cexp, cexpf, cexpl - complex exponential functions | 6016 SYNOPSIS | 6017 #include | 6018 double complex cexp(double complex z); | 6019 float complex cexpf(float complex z); | 6020 long double complex cexpl(long double complex z); | 6021 DESCRIPTION | 6022 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 6023 conflict between the requirements described here and the ISO C standard is unintentional. This | 6024 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 6025 These functions shall compute the complex exponent of z, defined as ez. | 6026 RETURN VALUE | 6027 These functions shall return the complex exponential value of z. | 6028 ERRORS | 6029 No errors are defined. | 6030 EXAMPLES | 6031 None. | 6032 APPLICATION USAGE | 6033 None. | 6034 RATIONALE | 6035 None. | 6036 FUTURE DIRECTIONS | 6037 None. | 6038 SEE ALSO | 6039 clog( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 6040 CHANGE HISTORY || 6041 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | 674 Technical Standard (2000) (Draft July 31, 2000) System Interfaces cfgetispeed( ) 6042 NAME 6043 cfgetispeed - get input baud rate 6044 SYNOPSIS 6045 #include 6046 speed_t cfgetispeed(const struct termios *termios_p); 6047 DESCRIPTION 6048 The cfgetispeed( ) function shall extract the input baud rate from the termios structure to which 6049 the termios_p argument points. 6050 This function shall return exactly the value in the termios data structure, without interpretation. 6051 RETURN VALUE 6052 Upon successful completion, cfgetispeed( ) shall return a value of type speed_t representing the 6053 input baud rate. 6054 ERRORS 6055 No errors are defined. 6056 EXAMPLES 6057 None. 6058 APPLICATION USAGE 6059 None. 6060 RATIONALE 6061 The term baud is used historically here, but is not technically correct. This is properly ``bits per 6062 second'', which may not be the same as baud. However, the term is used because of the 6063 historical usage and understanding. 6064 The cfgetospeed( ), cfgetispeed( ), cfsetospeed( ), and cfsetispeed( ) functions do not take arguments as 6065 numbers, but rather as symbolic names. There are two reasons for this: 6066 1. Historically, numbers were not used because of the way the rate was stored in the data 6067 structure. This is retained even though a function is now used. 6068 2. More importantly, only a limited set of possible rates is at all portable, and this constrains 6069 the application to that set. 6070 There is nothing to prevent an implementation to accept, as an extension, a number (such as 126) 6071 if it wished, and because the encoding of the Bxxx symbols is not specified, this can be done so 6072 no ambiguity is introduced. 6073 Setting the input baud rate to zero was a mechanism to allow for split baud rates. Clarifications 6074 in this volume of IEEE Std. 1003.1-200x have made it possible to determine whether split rates 6075 are supported and to support them without having to treat zero as a special case. Since this 6076 functionality is also confusing, it has been declared obsolescent. The 0 argument referred to is 6077 the literal constant 0, not the symbolic constant B0. This volume of IEEE Std. 1003.1-200x does 6078 not preclude B0 from being defined as the value 0; in fact, implementations would likely benefit 6079 from the two being equivalent. This volume of IEEE Std. 1003.1-200x does not fully specify 6080 whether the previous cfsetispeed( ) value is retained after a tcgetattr( ) as the actual value or as 6081 zero. Therefore, portable applications should always set both the input speed and output speed 6082 when setting either. 6083 In historical implementations, the baud rate information is traditionally kept in c_cflag. 6084 Applications should be written to presume that this might be the case (and thus not blindly copy 6085 c_cflag), but not to rely on it in case it is in some other field of the structure. Setting the c_cflag 6086 field absolutely after setting a baud rate is a non-portable action because of this. In general, the System Interfaces, Issue 6 675 cfgetispeed( ) System Interfaces 6087 unused parts of the flag fields might be used by the implementation and should not be blindly 6088 copied from the descriptions of one terminal device to another. 6089 FUTURE DIRECTIONS 6090 None. 6091 SEE ALSO 6092 cfgetospeed( ), cfsetispeed( ), cfsetospeed( ), tcgetattr( ), the Base Definitions volume of | 6093 IEEE Std. 1003.1-200x, , the Base Definitions volume of IEEE Std. 1003.1-200x, | 6094 Chapter 11, General Terminal Interface | 6095 CHANGE HISTORY 6096 First released in Issue 3. 6097 Entry included for alignment with the POSIX.1-1988 standard. 6098 Issue 4 6099 The following changes are incorporated for alignment with the ISO POSIX-1 standard: 6100 * The type of the argument termios_p is changed from struct termios* to const struct termios*. 6101 * The DESCRIPTION is changed to indicate that the function simply returns the value from 6102 termios_p, irrespective of how that structure was obtained. Issue 3 states that if termios_p was 6103 not obtained by a successful call to tcgetattr( ), the behavior is undefined. 676 Technical Standard (2000) (Draft July 31, 2000) System Interfaces cfgetospeed( ) 6104 NAME 6105 cfgetospeed - get output baud rate 6106 SYNOPSIS 6107 #include 6108 speed_t cfgetospeed(const struct termios *termios_p); 6109 DESCRIPTION 6110 The cfgetospeed( ) function shall extract the output baud rate from the termios structure to which 6111 the termios_p argument points. 6112 This function shall return exactly the value in the termios data structure, without interpretation. 6113 RETURN VALUE 6114 Upon successful completion, cfgetospeed( ) shall return a value of type speed_t representing the 6115 output baud rate. 6116 ERRORS 6117 No errors are defined. 6118 EXAMPLES 6119 None. 6120 APPLICATION USAGE 6121 None. 6122 RATIONALE 6123 Refer to cfgetispeed( ). 6124 FUTURE DIRECTIONS 6125 None. 6126 SEE ALSO 6127 cfgetispeed( ), cfsetispeed( ), cfsetospeed( ), tcgetattr( ), the Base Definitions volume of | 6128 IEEE Std. 1003.1-200x, , the Base Definitions volume of IEEE Std. 1003.1-200x, | 6129 Chapter 11, General Terminal Interface | 6130 CHANGE HISTORY 6131 First released in Issue 3. 6132 Entry included for alignment with the POSIX.1-1988 standard. 6133 Issue 4 6134 The following changes are incorporated for alignment with the ISO POSIX-1 standard: 6135 * The type of the argument termios_p is changed from struct termios* to const struct termios*. 6136 * The DESCRIPTION is changed to indicate that the function simply returns the value from 6137 termios_p, irrespective of how that structure was obtained. Issue 3 states that if termios_p was 6138 not obtained by a successful call to tcgetattr( ), the behavior is undefined. System Interfaces, Issue 6 677 cfsetispeed( ) System Interfaces 6139 NAME 6140 cfsetispeed - set input baud rate 6141 SYNOPSIS 6142 #include 6143 int cfsetispeed(struct termios *termios_p, speed_t speed); 6144 DESCRIPTION 6145 The cfsetispeed( ) function shall set the input baud rate stored in the structure pointed to by 6146 termios_p to speed. 6147 There shall be no effect on the baud rates set in the hardware until a subsequent successful call 6148 to tcsetattr( ) with the same termios structure. Similarly, errors resulting from attempts to set 6149 baud rates not supported by the terminal device need not be detected until the tcsetattr( ) 6150 function is called. 6151 RETURN VALUE 6152 Upon successful completion, cfsetispeed( ) shall return 0; otherwise, -1 shall be returned, and | 6153 errno may be set to indicate the error. | 6154 ERRORS 6155 The cfsetispeed( ) function may fail if: 6156 [EINVAL] The speed value is not a valid baud rate. | 6157 [EINVAL] The value of speed is outside the range of possible speed values as specified in | 6158 . | 6159 EXAMPLES 6160 None. 6161 APPLICATION USAGE 6162 None. 6163 RATIONALE 6164 Refer to cfgetispeed( ). 6165 FUTURE DIRECTIONS 6166 None. 6167 SEE ALSO 6168 cfgetispeed( ), cfgetospeed( ), cfsetospeed( ), tcsetattr( ), the Base Definitions volume of | 6169 IEEE Std. 1003.1-200x, , the Base Definitions volume of IEEE Std. 1003.1-200x, | 6170 Chapter 11, General Terminal Interface | 6171 CHANGE HISTORY 6172 First released in Issue 3. 6173 Entry included for alignment with the POSIX.1-1988 standard. 6174 Issue 4 6175 The first description of the [EINVAL] error is added and is marked as an extension. | 6176 Issue 4, Version 2 6177 The ERRORS section is changed to indicate that [EINVAL] may be returned if the specified 6178 speed is outside the range of possible speed values given in . 678 Technical Standard (2000) (Draft July 31, 2000) System Interfaces cfsetispeed( ) 6179 Issue 6 6180 The following new requirements on POSIX implementations derive from alignment with the 6181 Single UNIX Specification: 6182 * The optional setting of errno and the [EINVAL] error conditions are added. System Interfaces, Issue 6 679 cfsetospeed( ) System Interfaces 6183 NAME 6184 cfsetospeed - set output baud rate 6185 SYNOPSIS 6186 #include 6187 int cfsetospeed(struct termios *termios_p, speed_t speed); 6188 DESCRIPTION 6189 The cfsetospeed( ) function shall set the output baud rate stored in the structure pointed to by 6190 termios_p to speed. 6191 There shall be no effect on the baud rates set in the hardware until a subsequent successful call 6192 to tcsetattr( ) with the same termios structure. Similarly, errors resulting from attempts to set 6193 baud rates not supported by the terminal device need not be detected until the tcsetattr( ) 6194 function is called. 6195 RETURN VALUE 6196 Upon successful completion, cfsetospeed( ) shall return 0; otherwise, it shall return -1 and errno | 6197 may be set to indicate the error. | 6198 ERRORS 6199 The cfsetospeed( ) function may fail if: 6200 [EINVAL] The speed value is not a valid baud rate. | 6201 [EINVAL] The value of speed is outside the range of possible speed values as specified in | 6202 . | 6203 EXAMPLES 6204 None. 6205 APPLICATION USAGE 6206 None. 6207 RATIONALE 6208 Refer to cfgetispeed( ). 6209 FUTURE DIRECTIONS 6210 None. 6211 SEE ALSO 6212 cfgetispeed( ), cfgetospeed( ), cfsetispeed( ), tcsetattr( ), the Base Definitions volume of | 6213 IEEE Std. 1003.1-200x, , the Base Definitions volume of IEEE Std. 1003.1-200x, | 6214 Chapter 11, General Terminal Interface | 6215 CHANGE HISTORY 6216 First released in Issue 3. 6217 Entry included for alignment with the POSIX.1-1988 standard. 6218 Issue 4 6219 The first description of the [EINVAL] error is added and is marked as an extension. | 6220 Issue 4, Version 2 6221 The ERRORS section is changed to indicate that [EINVAL] may be returned if the specified 6222 speed is outside the range of possible speed values given in . 680 Technical Standard (2000) (Draft July 31, 2000) System Interfaces cfsetospeed( ) 6223 Issue 6 6224 The following new requirements on POSIX implementations derive from alignment with the 6225 Single UNIX Specification: 6226 * The optional setting of errno and the [EINVAL] error conditions are added. System Interfaces, Issue 6 681 chdir( ) System Interfaces 6227 NAME 6228 chdir - change working directory 6229 SYNOPSIS 6230 #include 6231 int chdir(const char *path); 6232 DESCRIPTION 6233 The chdir( ) function shall cause the directory named by the path name pointed to by the path 6234 argument to become the current working directory; that is, the starting point for path searches 6235 for path names not beginning with '/'. 6236 RETURN VALUE 6237 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned, the current 6238 working directory shall remain unchanged, and errno shall be set to indicate the error. 6239 ERRORS 6240 The chdir( ) function shall fail if: 6241 [EACCES] Search permission is denied for any component of the path name. | 6242 [ELOOP] A loop exists in symbolic links encountered during resolution of the path | 6243 argument. | 6244 [ENAMETOOLONG] | 6245 The length of the path argument exceeds {PATH_MAX} or a path name | 6246 component is longer than {NAME_MAX}. | 6247 [ENOENT] A component of path does not name an existing directory or path is an empty | 6248 string. 6249 [ENOTDIR] A component of the path name is not a directory. | 6250 The chdir( ) function may fail if: 6251 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 6252 resolution of the path argument. | 6253 [ENAMETOOLONG] | 6254 As a result of encountering a symbolic link in resolution of the path argument, 6255 the length of the substituted path name string exceeded {PATH_MAX}. | 6256 EXAMPLES 6257 Changing the Current Working Directory 6258 The following example makes the value pointed to by directory, /tmp, the current working 6259 directory. 6260 #include 6261 ... 6262 char *directory = "/tmp"; 6263 int ret; 6264 ret = chdir (directory); 682 Technical Standard (2000) (Draft July 31, 2000) System Interfaces chdir( ) 6265 APPLICATION USAGE 6266 The chdir( ) function only affects the working directory of the current process. The result if a 6267 NULL argument is passed to chdir( ) is unspecified because some implementations dynamically 6268 allocate space in that case. 6269 RATIONALE 6270 The chdir( ) function only affects the working directory of the current process. 6271 The result if a NULL argument is passed to chdir( ) is left implementation-defined because some | 6272 implementations dynamically allocate space in that case. | 6273 FUTURE DIRECTIONS 6274 None. 6275 SEE ALSO 6276 getcwd( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 6277 CHANGE HISTORY 6278 First released in Issue 1. Derived from Issue 1 of the SVID. | 6279 Issue 4 6280 The header is added to the SYNOPSIS section. 6281 The following change is incorporated for alignment with the ISO POSIX-1 standard: 6282 * The type of argument path is changed from char* to const char*. 6283 The following change is incorporated for alignment with the FIPS requirements: 6284 * In the ERRORS section, the condition whereby [ENAMETOOLONG] is returned if a path 6285 name component is larger that {NAME_MAX} is now defined as mandatory and marked as 6286 an extension. 6287 Issue 4, Version 2 6288 The ERRORS section is updated for X/OPEN UNIX conformance as follows: 6289 * It states that [ELOOP] is returned if too many symbolic links are encountered during path | 6290 name resolution. 6291 * A second [ENAMETOOLONG] condition is defined that may report excessive length of an | 6292 intermediate result of path name resolution of a symbolic link. 6293 Issue 6 6294 The APPLICATION USAGE section is added. 6295 The following changes are made for alignment with the ISO POSIX-1: 1996 standard: 6296 * The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. 6297 This is since behavior may vary from one file system to another. 6298 The following new requirements on POSIX implementations derive from alignment with the 6299 Single UNIX Specification: 6300 * The [ELOOP] mandatory error condition is added. 6301 * A second [ENAMETOOLONG] is added as an optional error condition. 6302 The following changes were made to align with the IEEE P1003.1a draft standard: 6303 * The [ELOOP] optional error condition is added. System Interfaces, Issue 6 683 chmod( ) System Interfaces 6304 NAME 6305 chmod - change mode of a file 6306 SYNOPSIS 6307 #include 6308 int chmod(const char *path, mode_t mode); 6309 DESCRIPTION 6310 XSI The chmod( ) function shall change S_ISUID, S_ISGID, S_ISVTX, and the file permission bits of 6311 the file named by the path name pointed to by the path argument to the corresponding bits in the 6312 mode argument. The application shall ensure that the effective user ID of the process matches the 6313 owner of the file or the process has appropriate privileges in order to do this. 6314 S_ISUID, S_ISGID, and the file permission bits are described in . 6315 XSI If a directory is writable and the mode bit S_ISVTX is set on the directory, a process may remove 6316 or rename files within that directory only if one or more of the following is true: 6317 * The effective user ID of the process is the same as that of the owner ID of the file. 6318 * The effective user ID of the process is the same as that of the owner ID of the directory. 6319 * The process has appropriate privileges. 6320 | 6321 XSI If the S_ISVTX bit is set on a non-directory file, the behavior is unspecified. 6322 If the calling process does not have appropriate privileges, and if the group ID of the file does 6323 not match the effective group ID or one of the supplementary group IDs and if the file is a 6324 regular file, bit S_ISGID (set-group-ID on execution) in the file's mode shall be cleared upon 6325 successful return from chmod( ). 6326 Additional implementation-defined restrictions may cause the S_ISUID and S_ISGID bits in | 6327 mode to be ignored. 6328 The effect on file descriptors for files open at the time of a call to chmod( ) is implementation- | 6329 defined. | 6330 Upon successful completion, chmod( ) shall mark for update the st_ctime field of the file. 6331 RETURN VALUE 6332 Upon successful completion, 0 shall be returned; otherwise, -1 shall be returned and errno set to 6333 indicate the error. If -1 is returned, no change to the file mode occurs. 6334 ERRORS 6335 The chmod( ) function shall fail if: 6336 [EACCES] Search permission is denied on a component of the path prefix. | 6337 [ELOOP] A loop exists in symbolic links encountered during resolution of the path | 6338 argument. | 6339 [ENAMETOOLONG] | 6340 The length of the path argument exceeds {PATH_MAX} or a path name 6341 component is longer than {NAME_MAX}. | 6342 [ENOTDIR] A component of the path prefix is not a directory. | 6343 [ENOENT] A component of path does not name an existing file or path is an empty string. | 6344 [EPERM] The effective user ID does not match the owner of the file and the process | 6345 does not have appropriate privileges. 684 Technical Standard (2000) (Draft July 31, 2000) System Interfaces chmod( ) 6346 [EROFS] The named file resides on a read-only file system. | 6347 The chmod( ) function may fail if: 6348 [EINTR] A signal was caught during execution of the function. | 6349 [EINVAL] The value of the mode argument is invalid. | 6350 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 6351 resolution of the path argument. | 6352 [ENAMETOOLONG] | 6353 As a result of encountering a symbolic link in resolution of the path argument, 6354 the length of the substituted path name strings exceeded {PATH_MAX}. | 6355 EXAMPLES 6356 Setting Read Permissions for User, Group, and Others 6357 The following example sets read permissions for the owner, group, and others. 6358 #include 6359 const char *path; 6360 ... 6361 chmod(path, S_IRUSR|S_IRGRP|S_IROTH); 6362 Setting Read, Write, and Execute Permissions for the Owner Only 6363 The following example sets read, write, and execute permissions for the owner, and no 6364 permissions for group and others. 6365 #include 6366 const char *path; 6367 ... 6368 chmod(path, S_IRWXU); 6369 Setting Different Permissions for Owner, Group, and Other 6370 The following example sets owner permissions for CHANGEFILE to read, write, and execute, 6371 group permissions to read and execute, and other permissions to read. 6372 #include 6373 #define CHANGEFILE "/etc/myfile" 6374 ... 6375 chmod(CHANGEFILE, S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH); 6376 Setting and Checking File Permissions 6377 The following example sets the file permission bits for a file named /home/cnd/mod1, then calls 6378 the stat( ) function to verify the permissions. 6379 #include 6380 #include 6381 int status; 6382 struct stat buffer 6383 ... System Interfaces, Issue 6 685 chmod( ) System Interfaces 6384 chmod("home/cnd/mod1", S_IRWXU|S_IRWXG|S_IROTH|S_IWOTH); 6385 status = stat("home/cnd/mod1", &buffer;); 6386 APPLICATION USAGE 6387 In order to ensure that the S_ISUID and S_ISGID bits are set, an application requiring this should 6388 use stat( ) after a successful chmod( ) to verify this. 6389 Any file descriptors currently open by any process on the file could possibly become invalid if | 6390 the mode of the file is changed to a value which would deny access to that process. One | 6391 situation where this could occur is on a stateless file system. This behavior will not occur in a | 6392 conforming environment. | 6393 RATIONALE 6394 This volume of IEEE Std. 1003.1-200x specifies that the S_ISGID bit is cleared by chmod( ) on a 6395 regular file under certain conditions. This is specified on the assumption that regular files may 6396 be executed, and the system should prevent users from making executable setgid( ) files perform 6397 with privileges that the caller does not have. On implementations that support execution of 6398 other file types, the S_ISGID bit should be cleared for those file types under the same 6399 circumstances. 6400 Implementations that use the S_ISUID bit to indicate some other function (for example, 6401 mandatory record locking) on non-executable files need not clear this bit on writing. They 6402 should clear the bit for executable files and any other cases where the bit grants special powers 6403 to processes that change the file contents. Similar comments apply to the S_ISGID bit. 6404 FUTURE DIRECTIONS 6405 None. 6406 SEE ALSO 6407 chown( ), mkdir( ), mkfifo( ), open( ), stat( ), statvfs( ), the Base Definitions volume of | 6408 IEEE Std. 1003.1-200x, , | 6409 CHANGE HISTORY 6410 First released in Issue 1. Derived from Issue 1 of the SVID. | 6411 Issue 4 6412 The header is now marked as optional (OH); this header need not be included on 6413 XSI-conformant systems. 6414 The [EINVAL] error is marked as an extension. 6415 The following change is incorporated for alignment with the ISO POSIX-1 standard: 6416 * The type of argument path is changed from char* to const char*. 6417 The following change is incorporated for alignment with the FIPS requirements: 6418 * In the ERRORS section, the condition whereby [ENAMETOOLONG] is returned if a path 6419 name component is larger that {NAME_MAX} is now defined as mandatory and marked as 6420 an extension. 6421 Issue 4, Version 2 6422 The following changes are incorporated for X/OPEN UNIX conformance: 6423 * The DESCRIPTION is updated to describe X/OPEN UNIX functionality relating to 6424 permission checks applied when removing or renaming files in a directory having the 6425 S_ISVTX bit set. 6426 * In the ERRORS section, the condition whereby [ELOOP] is returned if too many symbolic 6427 links are encountered during path name resolution is defined as mandatory, and [EINTR] is 686 Technical Standard (2000) (Draft July 31, 2000) System Interfaces chmod( ) 6428 added as an optional error. 6429 * In the ERRORS section, a second [ENAMETOOLONG] condition is defined that may report 6430 excessive length of an intermediate result of path name resolution of a symbolic link. 6431 Issue 6 6432 The following changes are made for alignment with the ISO POSIX-1: 1996 standard: 6433 * The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. 6434 This is since behavior may vary from one file system to another. 6435 The following new requirements on POSIX implementations derive from alignment with the 6436 Single UNIX Specification: 6437 * The requirement to include has been removed. Although was 6438 required for conforming implementations of previous POSIX specifications, it was not 6439 required for UNIX applications. 6440 * The [EINVAL] and [EINTR] optional error conditions are added. 6441 * A second [ENAMETOOLONG] is added as an optional error condition. 6442 The following changes were made to align with the IEEE P1003.1a draft standard: 6443 * The [ELOOP] optional error condition is added. 6444 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 687 chown( ) System Interfaces 6445 NAME 6446 chown - change owner and group of a file 6447 SYNOPSIS 6448 #include 6449 int chown(const char *path, uid_t owner, gid_t group); 6450 DESCRIPTION 6451 The path argument points to a path name naming a file. The user ID and group ID of the named 6452 file are set to the numeric values contained in owner and group, respectively. 6453 Only processes with an effective user ID equal to the user ID of the file or with appropriate 6454 privileges may change the ownership of a file. If _POSIX_CHOWN_RESTRICTED is in effect for 6455 path: 6456 * Changing the user ID is restricted to processes with appropriate privileges. 6457 * Changing the group ID is permitted to a process with an effective user ID equal to the user 6458 ID of the file, but without appropriate privileges, if and only if owner is equal to the file's user 6459 ID or (uid_t)-1 and group is equal either to the calling process' effective group ID or to one of 6460 its supplementary group IDs. 6461 If the specified file is a regular file, one or more of the S_IXUSR, S_IXGRP, or S_IXOTH bits of 6462 the file mode are set, and the process does not have appropriate privileges, the set-user-ID 6463 (S_ISUID) and set-group-ID (S_ISGID) bits of the file mode shall be cleared upon successful 6464 return from chown( ). If the specified file is a regular file, one or more of the S_IXUSR, S_IXGRP, 6465 or S_IXOTH bits of the file mode are set, and the process has appropriate privileges, it is | 6466 implementation-defined whether the set-user-ID and set-group-ID bits are altered. If the chown( ) | 6467 function is successfully invoked on a file that is not a regular file and one or more of the 6468 S_IXUSR, S_IXGRP, or S_IXOTH bits of the file mode are set, the set-user-ID and set-group-ID 6469 bits may be cleared. 6470 If owner or group is specified as (uid_t)-1 or (gid_t)-1, respectively, the corresponding ID of the 6471 file is unchanged. 6472 Upon successful completion, chown( ) shall mark for update the st_ctime field of the file. 6473 RETURN VALUE 6474 Upon successful completion, 0 shall be returned; otherwise, -1 shall be returned and errno set to 6475 indicate the error. If -1 is returned, no changes are made in the user ID and group ID of the file. 6476 ERRORS 6477 The chown( ) function shall fail if: 6478 [EACCES] Search permission is denied on a component of the path prefix. | 6479 [ELOOP] A loop exists in symbolic links encountered during resolution of the path | 6480 argument. 6481 [ENAMETOOLONG] | 6482 The length of the path argument exceeds {PATH_MAX} or a path name 6483 component is longer than {NAME_MAX}. | 6484 [ENOTDIR] A component of the path prefix is not a directory. | 6485 [ENOENT] A component of path does not name an existing file or path is an empty string. | 6486 [EPERM] The effective user ID does not match the owner of the file, or the calling | 6487 process does not have appropriate privileges and 6488 _POSIX_CHOWN_RESTRICTED indicates that such privilege is required. 688 Technical Standard (2000) (Draft July 31, 2000) System Interfaces chown( ) 6489 [EROFS] The named file resides on a read-only file system. | 6490 The chown( ) function may fail if: 6491 [EIO] An I/O error occurred while reading or writing to the file system. | 6492 [EINTR] The chown( ) function was interrupted by a signal which was caught. | 6493 [EINVAL] The owner or group ID supplied is not a value supported by the | 6494 implementation. 6495 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 6496 resolution of the path argument. 6497 [ENAMETOOLONG] | 6498 As a result of encountering a symbolic link in resolution of the path argument, 6499 the length of the substituted path name string exceeded {PATH_MAX}. 6500 EXAMPLES 6501 None. 6502 APPLICATION USAGE 6503 Although chown( ) can be used on some systems by the file owner to change the owner and 6504 group to any desired values, the only portable use of this function is to change the group of a file 6505 to the effective GID of the calling process or to a member of its group set. 6506 RATIONALE 6507 System III and System V allow a user to give away files; that is, the owner of a file may change 6508 its user ID to anything. This is a serious problem for implementations that are intended to meet 6509 government security regulations. Version 7 and 4.3 BSD permit only the superuser to change the 6510 user ID of a file. Some government agencies (usually not ones concerned directly with security) 6511 find this limitation too confining. This volume of IEEE Std. 1003.1-200x uses may to permit 6512 secure implementations while not disallowing System V. 6513 System III and System V allow the owner of a file to change the group ID to anything. Version 7 6514 permits only the superuser to change the group ID of a file. 4.3 BSD permits the owner to 6515 change the group ID of a file to its effective group ID or to any of the groups in the list of 6516 supplementary group IDs, but to no others. 6517 The POSIX.1-1990 standard requires that the chown( ) function invoked by a non-appropriate 6518 privileged process clear the S_ISGID and the S_ISUID bits for regular files, and permits them to 6519 be cleared for other types of files. This is so that changes in accessibility do not accidentally 6520 cause files to become security holes. Unfortunately, requiring these bits to be cleared on non- 6521 executable data files also clears the mandatory file locking bit (shared withwith S_ISGID), which | 6522 is an extension on many implementations (it first appeared in System V). These bits should only 6523 be required to be cleared on regular files that have one or more of their execute bits set. 6524 FUTURE DIRECTIONS 6525 None. 6526 SEE ALSO 6527 chmod( ), pathconf( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , | 6528 6529 CHANGE HISTORY 6530 First released in Issue 1. Derived from Issue 1 of the SVID. | System Interfaces, Issue 6 689 chown( ) System Interfaces 6531 Issue 4 6532 The header is now marked as optional (OH); this header need not be included on 6533 XSI-conformant systems. 6534 The value for owner of (uid_t)-1 is added to the DESCRIPTION to allow the use of -1 by the 6535 owner of a file to change the group ID only. 6536 The APPLICATION USAGE section is added. 6537 The following change is incorporated for alignment with the ISO POSIX-1 standard: 6538 * The type of argument path is changed from char* to const char*. 6539 The following changes are incorporated for alignment with the FIPS requirements: 6540 * In the ERRORS section, the condition whereby [ENAMETOOLONG] is returned if a path 6541 name component is larger that {NAME_MAX} is now defined as mandatory and marked as 6542 an extension. 6543 * In the ERRORS section, the condition whereby [EPERM] is returned when an attempt is 6544 made to change the user ID of a file and the caller does not have appropriate privileges is 6545 now defined as mandatory and marked as an extension. 6546 Issue 4, Version 2 6547 The ERRORS section is updated for X/OPEN UNIX conformance as follows: 6548 * It states that [ELOOP] is returned if too many symbolic links are encountered during path 6549 name resolution. 6550 * The [EIO] and [EINTR] optional conditions are added. 6551 * A second [ENAMETOOLONG] condition is defined that may report excessive length of an 6552 intermediate result of path name resolution of a symbolic link. 6553 Issue 6 6554 The following changes are made for alignment with the ISO POSIX-1: 1996 standard: 6555 * The wording describing the optional dependency on _POSIX_CHOWN_RESTRICTED is 6556 restored. 6557 * The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. 6558 This is since behavior may vary from one file system to another. 6559 * The [EPERM] error is restored as an error dependent on _POSIX_CHOWN_RESTRICTED. 6560 This is since its operand is a path name and applications should be aware that the error may 6561 not occur for that path name if the file system does not support 6562 _POSIX_CHOWN_RESTRICTED. 6563 The following new requirements on POSIX implementations derive from alignment with the 6564 Single UNIX Specification: 6565 * The requirement to include has been removed. Although was 6566 required for conforming implementations of previous POSIX specifications, it was not 6567 required for UNIX applications. 6568 * The value for owner of (uid_t)-1 allows the use of -1 by the owner of a file to change the 6569 group ID only. 6570 * The [ELOOP] mandatory error condition is added. 6571 * The [EIO] and [EINTR] optional error conditions are added. 690 Technical Standard (2000) (Draft July 31, 2000) System Interfaces chown( ) 6572 * A second [ENAMETOOLONG] is added as an optional error condition. 6573 The following changes were made to align with the IEEE P1003.1a draft standard: 6574 * Clarification is added that the S_ISUID and S_ISGID bits do not need to be cleared when the 6575 process has appropriate privileges. | 6576 * The [ELOOP] optional error condition is added. System Interfaces, Issue 6 691 cimag( ) System Interfaces 6577 NAME | 6578 cimag, cimagf, cimagl - complex imaginary functions | 6579 SYNOPSIS | 6580 #include | 6581 double cimag(double complex z); | 6582 float cimagf(float complex z); | 6583 long double cimagl(long double complex z); | 6584 DESCRIPTION | 6585 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 6586 conflict between the requirements described here and the ISO C standard is unintentional. This | 6587 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 6588 These functions shall compute the imaginary part of z. | 6589 RETURN VALUE | 6590 These functions shall return the imaginary part value (as a real). | 6591 ERRORS | 6592 No errors are defined. | 6593 EXAMPLES | 6594 None. | 6595 APPLICATION USAGE | 6596 For a variable z of complex type: | 6597 z == creal(z) + cimag(z)*I | 6598 RATIONALE | 6599 None. | 6600 FUTURE DIRECTIONS | 6601 None. | 6602 SEE ALSO | 6603 carg( ), conj( ), cproj( ), creal( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 6604 CHANGE HISTORY || 6605 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | 692 Technical Standard (2000) (Draft July 31, 2000) System Interfaces clearerr( ) 6606 NAME 6607 clearerr - clear indicators on a stream 6608 SYNOPSIS 6609 #include 6610 void clearerr(FILE *stream); 6611 DESCRIPTION 6612 CX The functionality described on this reference page is aligned with the ISO C standard. Any 6613 conflict between the requirements described here and the ISO C standard is unintentional. This 6614 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 6615 The clearerr( ) function shall clear the end-of-file and error indicators for the stream to which 6616 stream points. 6617 RETURN VALUE 6618 The clearerr( ) function shall return no value. 6619 ERRORS 6620 No errors are defined. 6621 EXAMPLES 6622 None. 6623 APPLICATION USAGE 6624 None. 6625 RATIONALE 6626 None. 6627 FUTURE DIRECTIONS 6628 None. 6629 SEE ALSO 6630 The Base Definitions volume of IEEE Std. 1003.1-200x, | 6631 CHANGE HISTORY 6632 First released in Issue 1. Derived from Issue 1 of the SVID. | System Interfaces, Issue 6 693 clock( ) System Interfaces 6633 NAME 6634 clock - report CPU time used 6635 SYNOPSIS 6636 #include 6637 clock_t clock(void); 6638 DESCRIPTION 6639 CX The functionality described on this reference page is aligned with the ISO C standard. Any 6640 conflict between the requirements described here and the ISO C standard is unintentional. This 6641 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 6642 The clock( ) function shall return the implementation's best approximation to the processor time 6643 used by the process since the beginning of an implementation-defined time related only to the | 6644 process invocation. | 6645 RETURN VALUE 6646 To determine the time in seconds, the value returned by clock( ) should be divided by the value 6647 XSI of the macro CLOCKS_PER_SEC. CLOCKS_PER_SEC is defined to be one million in . 6648 If the processor time used is not available or its value cannot be represented, the function shall 6649 return the value (clock_t)-1. 6650 ERRORS 6651 No errors are defined. 6652 EXAMPLES 6653 None. 6654 APPLICATION USAGE 6655 In order to measure the time spent in a program, clock( ) should be called at the start of the 6656 program and its return value subtracted from the value returned by subsequent calls. The value 6657 returned by clock( ) is defined for compatibility across systems that have clocks with different 6658 resolutions. The resolution on any particular system need not be to microsecond accuracy. 6659 The value returned by clock( ) may wrap around on some systems. For example, on a machine 6660 with 32-bit values for clock_t, it wraps after 2 147 seconds or 36 minutes. 6661 RATIONALE 6662 None. 6663 FUTURE DIRECTIONS 6664 None. 6665 SEE ALSO 6666 asctime( ), ctime( ), difftime( ), gmtime( ), localtime( ), mktime( ), strftime( ), strptime( ), time( ), utime( ), | 6667 the Base Definitions volume of IEEE Std. 1003.1-200x, | 6668 CHANGE HISTORY 6669 First released in Issue 1. Derived from Issue 1 of the SVID. | 6670 Issue 4 6671 Reference to the resolution of CLOCKS_PER_SEC is marked as an extension. 6672 The ERRORS section is added. 6673 Advice on how to calculate the time spent in a program is added to the APPLICATION USAGE 6674 section. 6675 The following changes are incorporated for alignment with the ISO C standard: 694 Technical Standard (2000) (Draft July 31, 2000) System Interfaces clock( ) 6676 * The header is added to the SYNOPSIS section. 6677 * The DESCRIPTION and RETURN VALUE sections, though functionally equivalent to Issue 6678 3, are rewritten for clarity and consistency with the ISO C standard. This issue also defines 6679 under what circumstances (clock_t)-1 can be returned by the function. 6680 * The function is no longer marked as an extension. System Interfaces, Issue 6 695 clock_getcpuclockid( ) System Interfaces 6681 NAME 6682 clock_getcpuclockid - access a process CPU-time clock (REALTIME) 6683 SYNOPSIS 6684 CPT #include 6685 int clock_getcpuclockid(pid_t pid, clockid_t *clock_id); | 6686 | 6687 DESCRIPTION 6688 The clock_getcpuclockid( ) function shall return the clock ID of the CPU-time clock of the process 6689 specified by pid. If the process described by pid exists and the calling process has permission, 6690 the clock ID of this clock shall be returned in clock_id. 6691 If pid is zero, the clock_getcpuclockid( ) function shall return the clock ID of the CPU-time clock of 6692 the process making the call, in clock_id. 6693 The conditions under which one process has permission to obtain the CPU-time clock ID of | 6694 other processes are implementation-defined. | 6695 RETURN VALUE 6696 Upon successful completion, clock_getcpuclockid( ) shall return zero; otherwise, an error number 6697 shall be returned to indicate the error. 6698 ERRORS 6699 The clock_getcpuclockid( ) function shall fail if: 6700 [EPERM] The requesting process does not have permission to access the CPU-time 6701 clock for the process. 6702 The clock_getcpuclockid( ) function may fail if: 6703 [ESRCH] No process can be found corresponding to the process specified by pid. | 6704 EXAMPLES 6705 None. 6706 APPLICATION USAGE 6707 The clock_getcpuclockid( ) function is part of the Process CPU-Time Clocks option and need not | 6708 be provided on all implementations. | 6709 RATIONALE 6710 None. 6711 FUTURE DIRECTIONS 6712 None. 6713 SEE ALSO 6714 clock_getres( ), timer_create( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 6715 CHANGE HISTORY 6716 First released in Issue 6. Derived from IEEE Std. 1003.1d-1999. 6717 In the SYNOPSIS, the inclusion of is no longer required. 696 Technical Standard (2000) (Draft July 31, 2000) System Interfaces clock_getres( ) 6718 NAME 6719 clock_getres, clock_gettime, clock_settime - clock and timer functions (REALTIME) 6720 SYNOPSIS 6721 TMR #include 6722 int clock_getres(clockid_t clock_id, struct timespec *res); 6723 int clock_settime(clockid_t clock_id, const struct timespec *tp); 6724 int clock_gettime(clockid_t clock_id, struct timespec *tp); 6725 6726 DESCRIPTION 6727 The resolution of any clock can be obtained by calling clock_getres( ). Clock resolutions are | 6728 implementation-defined and cannot be set by a process. If the argument res is not NULL, the | 6729 resolution of the specified clock shall be stored in the location pointed to by res. If res is NULL, 6730 the clock resolution is not returned. If the time argument of clock_settime( ) is not a multiple of res, 6731 then the value is truncated to a multiple of res. 6732 The clock_gettime( ) function shall return the current value tp for the specified clock, clock_id. 6733 The clock_settime( ) function shall set the specified clock, clock_id, to the value specified by tp. 6734 Time values that are between two consecutive non-negative integer multiples of the resolution 6735 of the specified clock are truncated down to the smaller multiple of the resolution. 6736 A clock may be system-wide (that is, visible to all processes) or per-process (measuring time that 6737 is meaningful only within a process). All implementations shall support a clock_id of 6738 CLOCK_REALTIME defined in . This clock represents the realtime clock for the 6739 system. For this clock, the values returned by clock_gettime( ) and specified by clock_settime( ) 6740 represent the amount of time (in seconds and nanoseconds) since the Epoch. An implementation 6741 may also support additional clocks. The interpretation of time values for these clocks is 6742 unspecified. 6743 If the value of the CLOCK_REALTIME clock is set via clock_settime( ), the new value of the clock 6744 shall be used to determine the time of expiration for absolute time services based upon the 6745 CLOCK_REALTIME clock. This applies to the time at which armed absolute timers expire. If the 6746 absolute time requested at the invocation of such a time service is before the new value of the 6747 clock, the time service shall expire immediately as if the clock had reached the requested time 6748 normally. 6749 Setting the value of the CLOCK_REALTIME clock via clock_settime( ) shall have no effect on 6750 threads that are blocked waiting for a relative time service based upon this clock, including the 6751 nanosleep( ) function; nor on the expiration of relative timers based upon this clock. 6752 Consequently, these time services shall expire when the requested relative interval elapses, 6753 independently of the new or old value of the clock. 6754 MON If the Monotonic Clock option is supported, all implementations shall support a clock_id of 6755 CLOCK_MONOTONIC defined in . This clock represents the monotonic clock for the 6756 system. For this clock, the value returned by clock_gettime( ) represents the amount of time (in 6757 seconds and nanoseconds) since an unspecified point in the past (for example, system start-up 6758 time, or the Epoch). This point does not change after system start-up time. The value of the 6759 CLOCK_MONOTONIC clock cannot be set via clock_settime( ). This function shall fail if it is 6760 invoked with a clock_id argument of CLOCK_MONOTONIC. 6761 The effect of setting a clock via clock_settime( ) on armed per-process timers associated with a 6762 clock other than CLOCK_REALTIME is implementation-defined. | 6763 CS If the value of the CLOCK_REALTIME clock is set via clock_settime( ), the new value of the clock 6764 shall be used to determine the time at which the system shall awaken a thread blocked on an System Interfaces, Issue 6 697 clock_getres( ) System Interfaces 6765 absolute clock_nanosleep( ) call based upon the CLOCK_REALTIME clock. If the absolute time 6766 requested at the invocation of such a time service is before the new value of the clock, the call 6767 shall return immediately as if the clock had reached the requested time normally. 6768 Setting the value of the CLOCK_REALTIME clock via clock_settime( ) shall have no effect on any 6769 thread that is blocked on a relative clock_nanosleep( ) call. Consequently, the call shall return 6770 when the requested relative interval elapses, independently of the new or old value of the clock. 6771 The appropriate privilege to set a particular clock is implementation-defined. | 6772 CPT If _POSIX_CPUTIME is defined, implementations shall support clock ID values obtained by 6773 invoking clock_getcpuclockid( ), which represent the CPU-time clock of a given process. 6774 Implementations shall also support the special clockid_t value 6775 CLOCK_PROCESS_CPUTIME_ID, which represents the CPU-time clock of the calling process 6776 when invoking one of the clock_*( ) or timer_*( ) functions. For these clock IDs, the values | 6777 returned by clock_gettime( ) and specified by clock_settime( ) represent the amount of execution 6778 time of the process associated with the clock. Changing the value of a CPU-time clock via 6779 clock_settime( ) shall have no effect on the behavior of the sporadic server scheduling policy (see 6780 Scheduling Policies (on page 546)). 6781 TCT If _POSIX_THREAD_CPUTIME is defined, implementations shall support clock ID values 6782 obtained by invoking pthread_getcpuclockid( ), which represent the CPU-time clock of a given 6783 thread. Implementations shall also support the special clockid_t value 6784 CLOCK_THREAD_CPUTIME_ID, which represents the CPU-time clock of the calling thread 6785 when invoking one of the clock_*( ) or timer_*( ) functions. For these clock IDs, the values | 6786 returned by clock_gettime( ) and specified by clock_settime( ) represent the amount of execution 6787 time of the thread associated with the clock. Changing the value of a CPU-time clock via 6788 clock_settime( ) shall have no effect on the behavior of the sporadic server scheduling policy (see 6789 Scheduling Policies (on page 546)). 6790 RETURN VALUE 6791 A return value of 0 shall indicate that the call succeeded. A return value of -1 shall indicate that 6792 an error occurred, and errno shall be set to indicate the error. 6793 ERRORS 6794 The clock_getres( ), clock_gettime( ), and clock_settime( ) functions shall fail if: 6795 [EINVAL] The clock_id argument does not specify a known clock. | 6796 The clock_settime( ) function shall fail if: 6797 [EINVAL] The tp argument to clock_settime( ) is outside the range for the given clock ID. | 6798 [EINVAL] The tp argument specified a nanosecond value less than zero or greater than 6799 or equal to 1 000 million. 6800 MON [EINVAL] The value of the clock_id argument is CLOCK_MONOTONIC. 6801 The clock_settime( ) function may fail if: 6802 [EPERM] The requesting process does not have the appropriate privilege to set the | 6803 specified clock. 698 Technical Standard (2000) (Draft July 31, 2000) System Interfaces clock_getres( ) 6804 EXAMPLES 6805 None. 6806 APPLICATION USAGE 6807 These functions are part of the Timers option and need not be available on all implementations. | 6808 Note that the absolute value of the monotonic clock is meaningless (because its origin is 6809 arbitrary), and thus there is no need to set it. Furthermore, realtime applications can rely on the 6810 fact that the value of this clock is never set and, therefore, that time intervals measured with this 6811 clock will not be affected by calls to clock_settime( ). 6812 RATIONALE 6813 None. 6814 FUTURE DIRECTIONS 6815 None. 6816 SEE ALSO 6817 clock_getcpuclockid( ), clock_nanosleep( ), ctime( ), mq_timedreceive( ), mq_timedsend( ), nanosleep( ), 6818 pthread_mutex_timedlock( ), sem_timedwait( ), time( ), timer_create( ), timer_getoverrun( ), the Base | 6819 Definitions volume of IEEE Std. 1003.1-200x, | 6820 CHANGE HISTORY 6821 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 6822 Issue 6 6823 The [ENOSYS] error condition has been removed as stubs need not be provided if an 6824 implementation does not support the Timers option. | 6825 The APPLICATION USAGE section is added. 6826 The following changes were made to align with the IEEE P1003.1a draft standard: 6827 * Clarification is added of the effect of resetting the clock resolution. 6828 CPU-time clocks and the clock_getcpuclockid( ) function are added for alignment with 6829 IEEE Std. 1003.1d-1999. 6830 The following changes are added for alignment with IEEE Std. 1003.1j-2000: 6831 * The DESCRIPTION is updated as follows: 6832 - The value returned by clock_gettime( ) for CLOCK_MONOTONIC is specified. 6833 - clock_settime( ) failing for CLOCK_MONOTONIC is specified. 6834 - The effects of clock_settime( ) on the clock_nanosleep( ) function with respect to 6835 CLOCK_REALTIME is specified. 6836 * An [EINVAL] error is added to the ERRORS section, indicating that clock_settime( ) fails for 6837 CLOCK_MONOTONIC. 6838 * The APPLICATION USAGE section notes that the CLOCK_MONOTONIC clock need not 6839 and shall not be set by clock_settime( ) since the absolute value of the CLOCK_MONOTONIC 6840 clock is meaningless. 6841 * The clock_nanosleep( ), mq_timedreceive( ), mq_timedsend( ), pthread_mutex_timedlock( ), 6842 sem_timedwait( ), timer_create( ), and timer_settime( ) functions are added to the SEE ALSO 6843 section. System Interfaces, Issue 6 699 clock_nanosleep( ) System Interfaces 6844 NAME 6845 clock_nanosleep - high resolution sleep with specifiable clock 6846 SYNOPSIS 6847 CS #include 6848 int clock_nanosleep(clockid_t clock_id, int flags, 6849 const struct timespec *rqtp, struct timespec *rmtp); 6850 6851 DESCRIPTION 6852 If the flag TIMER_ABSTIME is not set in the flags argument, the clock_nanosleep( ) function shall 6853 cause the current thread to be suspended from execution until either the time interval specified 6854 by the rqtp argument has elapsed, or a signal is delivered to the calling thread and its action is to 6855 invoke a signal-catching function, or the process is terminated. The clock used to measure the 6856 time shall be the clock specified by clock_id. 6857 If the flag TIMER_ABSTIME is set in the flags argument, the clock_nanosleep( ) function shall 6858 cause the current thread to be suspended from execution until either the time value of the clock 6859 specified by clock_id reaches the absolute time specified by the rqtp argument, or a signal is 6860 delivered to the calling thread and its action is to invoke a signal-catching function, or the 6861 process is terminated. If, at the time of the call, the time value specified by rqtp is less than or 6862 equal to the time value of the specified clock, then clock_nanosleep( ) shall return immediately 6863 and the calling process shall not be suspended. 6864 The suspension time caused by this function may be longer than requested because the 6865 argument value is rounded up to an integer multiple of the sleep resolution, or because of the 6866 scheduling of other activity by the system. But, except for the case of being interrupted by a 6867 signal, the suspension time for the relative clock_nanosleep( ) function (that is, with the 6868 TIMER_ABSTIME flag not set) shall not be less than the time interval specified by rqtp, as 6869 measured by the corresponding clock. The suspension for the absolute clock_nanosleep( ) function 6870 (that is, with the TIMER_ABSTIME flag set) shall be in effect at least until the value of the 6871 corresponding clock reaches the absolute time specified by rqtp, except for the case of being 6872 interrupted by a signal. 6873 The use of the clock_nanosleep( ) function shall have no effect on the action or blockage of any 6874 signal. 6875 The clock_nanosleep( ) function shall fail if the clock_id argument refers to the CPU-time clock of 6876 the calling thread. It is unspecified if clock_id values of other CPU-time clocks are allowed. 6877 RETURN VALUE 6878 If the clock_nanosleep( ) function returns because the requested time has elapsed, its return value 6879 shall be zero. 6880 If the clock_nanosleep( ) function returns because it has been interrupted by a signal, it shall return 6881 the corresponding error value. For the relative clock_nanosleep( ) function, if the rmtp argument is 6882 non-NULL, the timespec structure referenced by it shall be updated to contain the amount of 6883 time remaining in the interval (the requested time minus the time actually slept). If the rmtp 6884 argument is NULL, the remaining time is not returned. The absolute clock_nanosleep( ) function 6885 has no effect on the structure referenced by rmtp. 6886 If clock_nanosleep( ) fails, it shall return the corresponding error value. 700 Technical Standard (2000) (Draft July 31, 2000) System Interfaces clock_nanosleep( ) 6887 ERRORS 6888 The clock_nanosleep( ) function shall fail if: 6889 [EINTR] The clock_nanosleep( ) function was interrupted by a signal. 6890 [EINVAL] The rqtp argument specified a nanosecond value less than zero or greater than 6891 or equal to 1 000 million; or the TIMER_ABSTIME flag was specified in flags 6892 and the rqtp argument is outside the range for the clock specified by clock_id; 6893 or the clock_id argument does not specify a known clock, or specifies the 6894 CPU-time clock of the calling thread. 6895 [ENOTSUP] The clock_id argument specifies a clock for which clock_nanosleep( ) is not 6896 supported, such as a CPU-time clock. 6897 EXAMPLES 6898 None. 6899 APPLICATION USAGE 6900 Calling clock_nanosleep( ) with the value TIMER_ABSTIME not set in the flags argument and with 6901 a clock_id of CLOCK_REALTIME is equivalent to calling nanosleep( ) with the same rqtp and rmtp 6902 arguments. 6903 RATIONALE 6904 The nanosleep( ) function specifies that the system-wide clock CLOCK_REALTIME is used to 6905 measure the elapsed time for this time service. However, with the introduction of the monotonic 6906 clock CLOCK_MONOTONIC a new relative sleep function is needed to allow an application to 6907 take advantage of the special characteristics of this clock. 6908 There are many applications in which a process needs to be suspended and then activated 6909 multiple times in a periodic way; for example, to poll the status of a non-interrupting device or 6910 to refresh a display device. For these cases, it is known that precise periodic activation cannot be 6911 achieved with a relative sleep( ) or nanosleep( ) function call. Suppose, for example, a periodic 6912 process that is activated at time T0, executes for a while, and then wants to suspend itself until 6913 time T0+T, the period being T. If this process wants to use the nanosleep( ) function, it must first 6914 call clock_gettime( ) to get the current time, then calculate the difference between the current time 6915 and T0+T and, finally, call nanosleep( ) using the computed interval. However, the process could 6916 be preempted by a different process between the two function calls, and in this case the interval 6917 computed would be wrong; the process would wake up later than desired. This problem would 6918 not occur with the absolute clock_nanosleep( ) function, since only one function call would be 6919 necessary to suspend the process until the desired time. In other cases, however, a relative sleep 6920 is needed, and that is why both functionalities are required. 6921 Although it is possible to implement periodic processes using the timers interface, this 6922 implementation would require the use of signals, and the reservation of some signal numbers. In 6923 this regard, the reasons for including an absolute version of the clock_nanosleep( ) function in 6924 IEEE Std. 1003.1-200x are the same as for the inclusion of the relative nanosleep( ). 6925 It is also possible to implement precise periodic processes using pthread_cond_timedwait( ), in 6926 which an absolute timeout is specified that takes effect if the condition variable involved is 6927 never signaled. However, the use of this interface is unnatural, and involves performing other 6928 operations on mutexes and condition variables that imply an unnecessary overhead. 6929 Furthermore, pthread_cond_timedwait( ) is not available in implementations that do not support 6930 threads. 6931 Although the interface of the relative and absolute versions of the new high resolution sleep 6932 service is the same clock_nanosleep( ) function, the rmtp argument is only used in the relative 6933 sleep. This argument is needed in the relative clock_nanosleep( ) function to reissue the function System Interfaces, Issue 6 701 clock_nanosleep( ) System Interfaces 6934 call if it is interrupted by a signal, but it is not needed in the absolute clock_nanosleep( ) function 6935 call; if the call is interrupted by a signal, the absolute clock_nanosleep( ) function can be invoked 6936 again with the same rqtp argument used in the interrupted call. 6937 FUTURE DIRECTIONS 6938 None. 6939 SEE ALSO 6940 clock_getres( ), nanosleep( ), pthread_cond_timedwait( ), sleep( ), the Base Definitions volume of | 6941 IEEE Std. 1003.1-200x, | 6942 CHANGE HISTORY | 6943 First released in Issue 6. Derived from IEEE Std. 1003.1j-2000. 702 Technical Standard (2000) (Draft July 31, 2000) System Interfaces clog( ) 6944 NAME | 6945 clog, clogf, clogl - complex natural logarithm functions | 6946 SYNOPSIS | 6947 #include | 6948 double complex clog(double complex z); | 6949 float complex clogf(float complex z); | 6950 long double complex clogl(long double complex z); | 6951 DESCRIPTION | 6952 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 6953 conflict between the requirements described here and the ISO C standard is unintentional. This | 6954 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 6955 These functions shall compute the complex natural (base e) logarithm of z, with a branch cut | 6956 along the negative real axis. | 6957 RETURN VALUE | 6958 These functions shall return the complex natural logarithm value, in the range of a strip | 6959 mathematically unbounded along the real axis and in the interval [-i , +i ] along the imaginary | 6960 axis. | 6961 ERRORS | 6962 No errors are defined. | 6963 EXAMPLES | 6964 None. | 6965 APPLICATION USAGE | 6966 None. | 6967 RATIONALE | 6968 None. | 6969 FUTURE DIRECTIONS | 6970 None. | 6971 SEE ALSO | 6972 cexp( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 6973 CHANGE HISTORY || 6974 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 703 close( ) System Interfaces 6975 NAME 6976 close - close a file descriptor 6977 SYNOPSIS 6978 #include 6979 int close(int fildes); 6980 DESCRIPTION 6981 The close( ) function shall deallocate the file descriptor indicated by fildes. To deallocate means 6982 to make the file descriptor available for return by subsequent calls to open( ) or other functions 6983 that allocate file descriptors. All outstanding record locks owned by the process on the file 6984 associated with the file descriptor shall be removed (that is, unlocked). 6985 If close( ) is interrupted by a signal that is to be caught, it shall return -1 with errno set to [EINTR] | 6986 and the state of fildes is unspecified. If an I/O error occurred while reading from or writing to the 6987 file system during close( ), it may return -1 with errno set to [EIO]; if this error is returned, the 6988 state of fildes is unspecified. 6989 When all file descriptors associated with a pipe or FIFO special file are closed, any data 6990 remaining in the pipe or FIFO shall be discarded. 6991 When all file descriptors associated with an open file description have been closed the open file 6992 description shall be freed. 6993 If the link count of the file is 0, when all file descriptors associated with the file are closed, the 6994 space occupied by the file shall be freed and the file shall no longer be accessible. 6995 XSR If a STREAMS-based fildes is closed and the calling process was previously registered to receive 6996 a SIGPOLL signal for events associated with that STREAM, the calling process shall be 6997 unregistered for events associated with the STREAM. The last close( ) for a STREAM causes the 6998 STREAM associated with fildes to be dismantled. If O_NONBLOCK is not set and there have 6999 been no signals posted for the STREAM, and if there is data on the module's write queue, close( ) 7000 waits for an unspecified time (for each module and driver) for any output to drain before 7001 dismantling the STREAM. The time delay can be changed via an I_SETCLTIME ioctl( ) request. If 7002 the O_NONBLOCK flag is set, or if there are any pending signals, close( ) does not wait for 7003 output to drain, and dismantles the STREAM immediately. 7004 If the implementation supports STREAMS-based pipes, and fildes is associated with one end of a 7005 pipe, the last close( ) causes a hangup to occur on the other end of the pipe. In addition, if the 7006 other end of the pipe has been named by fattach( ), then the last close( ) forces the named end to 7007 be detached by fdetach( ). If the named end has no open file descriptors associated with it and 7008 gets detached, the STREAM associated with that end is also dismantled. 7009 If fildes refers to the master side of a pseudo-terminal, and this is the last close, a SIGHUP signal 7010 is sent to the process group, if any, for which the slave side of the pseudo-terminal is the 7011 controlling terminal. It is unspecified whether closing the master side of the pseudo-terminal 7012 flushes all queued input and output. 7013 If fildes refers to the slave side of a STREAMS-based pseudo-terminal, a zero-length message 7014 may be sent to the master. 7015 AIO When there is an outstanding cancelable asynchronous I/O operation against fildes when close( ) 7016 is called, that I/O operation may be canceled. An I/O operation that is not canceled completes 7017 as if the close( ) operation had not yet occurred. All operations that are not canceled shall 7018 complete as if the close( ) blocked until the operations completed. The close( ) operation itself 7019 need not block awaiting such I/O completion. Whether any I/O operation is canceled, and 7020 which I/O operation may be canceled upon close( ), is implementation-defined. | 704 Technical Standard (2000) (Draft July 31, 2000) System Interfaces close( ) 7021 MF|SHM If a shared memory object or a memory mapped file remains referenced at the last close (that is, 7022 a process has it mapped), then the entire contents of the memory object shall persist until the 7023 memory object becomes unreferenced. If this is the last close of a shared memory object or a 7024 memory mapped file and the close results in the memory object becoming unreferenced, and the 7025 memory object has been unlinked, then the memory object shall be removed. 7026 If fildes refers to a socket, close( ) shall cause the socket to be destroyed. If the socket is in 7027 connection-mode, and the SO_LINGER option is set for the socket with non-zero linger time, 7028 and the socket has untransmitted data, then close( ) shall block for up to the current linger 7029 interval until all data is transmitted. 7030 RETURN VALUE 7031 Upon successful completion, 0 shall be returned; otherwise, -1 shall be returned and errno set to 7032 indicate the error. 7033 ERRORS 7034 The close( ) function shall fail if: 7035 [EBADF] The fildes argument is not a valid file descriptor. | 7036 [EINTR] The close( ) function was interrupted by a signal. | 7037 The close( ) function may fail if: 7038 [EIO] An I/O error occurred while reading from or writing to the file system. | 7039 EXAMPLES 7040 Reassigning a File Descriptor 7041 The following example closes the file descriptor associated with standard output for the current 7042 process, re-assigns standard output to a new file descriptor, and closes the original file 7043 descriptor to clean up. This example assumes that the file descriptor 0 (which is the descriptor | 7044 for standard input) is not closed. | 7045 #include 7046 ... 7047 int pfd; 7048 ... 7049 close(1); 7050 dup(pfd); 7051 close(pfd); 7052 ... 7053 Incidentally, this is exactly what could be achieved using: | 7054 dup2(pfd, 1); | 7055 close(pfd); | 7056 Closing a File Descriptor | 7057 In the following example, close( ) is used to close a file descriptor after an unsuccessful attempt is 7058 made to associate that file descriptor with a stream. 7059 #include 7060 #include 7061 #include System Interfaces, Issue 6 705 close( ) System Interfaces 7062 #define LOCKFILE "/etc/ptmp" 7063 ... 7064 int pfd; 7065 FILE *fpfd; 7066 ... 7067 if ((fpfd = fdopen (pfd, "w")) == NULL) { 7068 close(pfd); 7069 unlink(LOCKFILE); 7070 exit(1); 7071 } 7072 ... 7073 APPLICATION USAGE 7074 An application that had used the stdio routine fopen( ) to open a file should use the 7075 corresponding fclose( ) routine rather than close( ). Once a file is closed, the file descriptor no 7076 longer exists, since the integer corresponding to it no longer refers to a file. 7077 RATIONALE 7078 The use of interruptible device close routines should be discouraged to avoid problems with the 7079 implicit closes of file descriptors by exec and exit( ). This volume of IEEE Std. 1003.1-200x only | 7080 intends to permit such behavior by specifying the [EINTR] error condition. | 7081 FUTURE DIRECTIONS 7082 None. 7083 SEE ALSO 7084 fattach( ), fclose( ), fdetach( ), fopen( ), ioctl( ), open( ), the Base Definitions volume of | 7085 IEEE Std. 1003.1-200x, , Section 2.6 (on page 539) | 7086 CHANGE HISTORY 7087 First released in Issue 1. Derived from Issue 1 of the SVID. | 7088 Issue 4 7089 The header is added to the SYNOPSIS section. 7090 Issue 4, Version 2 7091 The following changes are incorporated for X/OPEN UNIX conformance: 7092 * The DESCRIPTION is updated to describe the actions of closing a file descriptor referring to 7093 a STREAMS-based file or either side of a pseudo-terminal. 7094 * The ERRORS section describes a condition under which the [EIO] error may be returned. 7095 Issue 5 7096 The DESCRIPTION is updated for alignment with the POSIX Realtime Extension. 7097 Issue 6 7098 The DESCRIPTION related to a STREAMS-based file or pseudo-terminal is marked as part of the 7099 XSI STREAMS Option Group. 7100 The following new requirements on POSIX implementations derive from alignment with the 7101 Single UNIX Specification: 7102 * The [EIO] error condition is added as an optional error. 7103 * The DESCRIPTION is updated to describe the state of the fildes file descriptor as unspecified 7104 if an I/O error occurs and an [EIO] error condition is returned. 7105 Text referring to sockets is added to the DESCRIPTION. 706 Technical Standard (2000) (Draft July 31, 2000) System Interfaces close( ) 7106 The DESCRIPTION is updated for alignment with IEEE Std. 1003.1j-2000 by specifying that 7107 shared memory objects and memory mapped files (and not typed memory objects) are the types 7108 of memory objects to which the paragraph on last closes applies. System Interfaces, Issue 6 707 closedir( ) System Interfaces 7109 NAME 7110 closedir - close a directory stream 7111 SYNOPSIS 7112 #include 7113 int closedir(DIR *dirp); 7114 DESCRIPTION 7115 The closedir( ) function shall close the directory stream referred to by the argument dirp. Upon 7116 return, the value of dirp may no longer point to an accessible object of the type DIR. If a file 7117 descriptor is used to implement type DIR, that file descriptor shall be closed. 7118 RETURN VALUE 7119 Upon successful completion, closedir( ) shall return 0; otherwise, -1 shall be returned and errno 7120 set to indicate the error. 7121 ERRORS 7122 The closedir( ) function may fail if: 7123 [EBADF] The dirp argument does not refer to an open directory stream. | 7124 [EINTR] The closedir( ) function was interrupted by a signal. | 7125 EXAMPLES 7126 Closing a Directory Stream 7127 The following program fragment demonstrates how the closedir( ) function is used. 7128 ... 7129 DIR *dir; 7130 struct dirent *dp; 7131 ... 7132 if ((dir = opendir (".")) == NULL) { 7133 ... 7134 } 7135 while ((dp = readdir (dir)) != NULL) { 7136 ... 7137 } 7138 closedir(dir); 7139 ... 7140 APPLICATION USAGE 7141 None. 7142 RATIONALE 7143 None. 7144 FUTURE DIRECTIONS 7145 None. 7146 SEE ALSO 7147 opendir( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 708 Technical Standard (2000) (Draft July 31, 2000) System Interfaces closedir( ) 7148 CHANGE HISTORY 7149 First released in Issue 2. 7150 Issue 4 7151 The header is now marked as optional (OH); this header need not be included on 7152 XSI-conformant systems. 7153 The [EINTR] error is marked as an extension. 7154 Issue 6 7155 In the SYNOPSIS, the inclusion of is no longer required. 7156 The following new requirements on POSIX implementations derive from alignment with the 7157 Single UNIX Specification: 7158 * The requirement to include has been removed. Although was 7159 required for conforming implementations of previous POSIX specifications, it was not 7160 required for UNIX applications. 7161 * The [EINTR] error condition is added as an optional error condition. System Interfaces, Issue 6 709 closelog( ) System Interfaces 7162 NAME 7163 closelog, openlog, setlogmask, syslog - control system log 7164 SYNOPSIS 7165 XSI #include 7166 void closelog(void); 7167 void openlog(const char *ident, int logopt, int facility); 7168 int setlogmask(int maskpri); 7169 void syslog(int priority, const char *message, ... /* arguments */); 7170 7171 DESCRIPTION 7172 The syslog( ) function shall send a message to an implementation-defined logging facility, which | 7173 may log it in an implementation-defined system log, write it to the system console, forward it to | 7174 a list of users, or forward it to the logging facility on another host over the network. The logged 7175 message shall include a message header and a message body. The message header contains at 7176 least a timestamp and a tag string. 7177 The message body is generated from the message and following arguments in the same manner 7178 as if these were arguments to printf( ), except that occurrences of %m in the format string 7179 pointed to by the message argument are replaced by the error message string associated with the 7180 current value of errno. A trailing character is added if needed. 7181 Values of the priority argument are formed by OR'ing together a severity level value and an 7182 optional facility value. If no facility value is specified, the current default facility value is used. 7183 Possible values of severity level include: 7184 LOG_EMERG A panic condition. 7185 LOG_ALERT A condition that should be corrected immediately, such as a corrupted system 7186 database. 7187 LOG_CRIT Critical conditions, such as hard device errors. 7188 LOG_ERR Errors. 7189 LOG_WARNING 7190 Warning messages. 7191 LOG_NOTICE Conditions that are not error conditions, but that may require special 7192 handling. 7193 LOG_INFO Informational messages. 7194 LOG_DEBUG Messages that contain information normally of use only when debugging a 7195 program. 7196 The facility indicates the application or system component generating the message. Possible 7197 facility values include: 7198 LOG_USER Messages generated by arbitrary processes. This is the default facility | 7199 identifier if none is specified. 7200 LOG_LOCAL0 Reserved for local use. 7201 LOG_LOCAL1 Reserved for local use. 7202 LOG_LOCAL2 Reserved for local use. 710 Technical Standard (2000) (Draft July 31, 2000) System Interfaces closelog( ) 7203 LOG_LOCAL3 Reserved for local use. 7204 LOG_LOCAL4 Reserved for local use. 7205 LOG_LOCAL5 Reserved for local use. 7206 LOG_LOCAL6 Reserved for local use. 7207 LOG_LOCAL7 Reserved for local use. 7208 The openlog( ) function shall set process attributes that affect subsequent calls to syslog( ). The 7209 ident argument is a string that is prepended to every message. The logopt argument indicates 7210 logging options. Values for logopt are constructed by a bitwise-inclusive OR of zero or more of 7211 the following: 7212 LOG_PID Log the process ID with each message. This is useful for identifying specific 7213 processes. 7214 LOG_CONS Write messages to the system console if they cannot be sent to the logging 7215 facility. The syslog( ) function ensures that the process does not acquire the 7216 console as a controlling terminal in the process of writing the message. 7217 LOG_NDELAY Open the connection to the logging facility immediately. Normally the open is 7218 delayed until the first message is logged. This is useful for programs that need 7219 to manage the order in which file descriptors are allocated. 7220 LOG_ODELAY Delay open until syslog( ) is called. 7221 LOG_NOWAIT Do not wait for child processes that may have been created during the course 7222 of logging the message. This option should be used by processes that enable 7223 notification of child termination using SIGCHLD, since syslog( ) may 7224 otherwise block waiting for a child whose exit status has already been 7225 collected. 7226 The facility argument encodes a default facility to be assigned to all messages that do not have 7227 an explicit facility already encoded. The initial default facility is LOG_USER. 7228 The openlog( ) and syslog( ) functions may allocate a file descriptor. It is not necessary to call 7229 openlog( ) prior to calling syslog( ). 7230 The closelog( ) function shall close any open file descriptors allocated by previous calls to 7231 openlog( ) or syslog( ). 7232 The setlogmask( ) function shall set the log priority mask for the current process to maskpri and 7233 return the previous mask. If the maskpri argument is 0, the current log mask is not modified. 7234 Calls by the current process to syslog( ) with a priority not set in maskpri shall be rejected. The 7235 default log mask allows all priorities to be logged. A call to openlog( ) is not required prior to | 7236 calling setlogmask( ). | 7237 Symbolic constants for use as values of the logopt, facility , priority, and maskpri arguments are 7238 defined in the header. 7239 RETURN VALUE 7240 The setlogmask( ) function shall return the previous log priority mask. The closelog( ), openlog( ), 7241 and syslog( ) functions shall return no value. 7242 ERRORS 7243 No errors are defined. System Interfaces, Issue 6 711 closelog( ) System Interfaces 7244 EXAMPLES 7245 Using openlog( ) 7246 The following example causes subsequent calls to syslog( ) to log the process ID with each 7247 message, and to write messages to the system console if they cannot be sent to the logging 7248 facility. 7249 #include 7250 char *ident = "Process demo"; 7251 int logopt = LOG_PID | LOG_CONS; 7252 int facility = LOG_USER; 7253 ... 7254 openlog(ident, logopt, facility); 7255 Using setlogmask( ) 7256 The following example causes subsequent calls to syslog( ) to accept error messages or messages | 7257 generated by arbitrary processes, and to reject all other messages. | 7258 #include 7259 int result; 7260 int mask = LOG_MASK (LOG_ERR | LOG_USER); 7261 ... 7262 result = setlogmask(mask); 7263 Using syslog 7264 The following example sends the message "This is a message" to the default logging 7265 facility, marking the message as an error message generated by random processes. 7266 #include 7267 char *message = "This is a message"; 7268 int priority = LOG_ERR | LOG_USER; 7269 ... 7270 syslog(priority, message); 7271 APPLICATION USAGE 7272 None. 7273 RATIONALE 7274 None. 7275 FUTURE DIRECTIONS 7276 None. 7277 SEE ALSO 7278 printf( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 7279 CHANGE HISTORY 7280 First released in Issue 4, Version 2. 712 Technical Standard (2000) (Draft July 31, 2000) System Interfaces closelog( ) 7281 Issue 5 7282 Moved from X/OPEN UNIX extension to BASE. System Interfaces, Issue 6 713 confstr( ) System Interfaces 7283 NAME 7284 confstr - get configurable variables 7285 SYNOPSIS 7286 #include 7287 size_t confstr(int name, char *buf, size_t len); 7288 DESCRIPTION 7289 The confstr( ) function provides a method for applications to get configuration-defined string 7290 values. Its use and purpose are similar to sysconf( ), but it is used where string values rather than 7291 numeric values are returned. 7292 The name argument represents the system variable to be queried. The implementation shall 7293 support the following name values, defined in . It may support others: 7294 _CS_PATH 7295 _CS_POSIX_V6_ILP32_OFF32_CFLAGS | 7296 _CS_POSIX_V6_ILP32_OFF32_LDFLAGS | 7297 _CS_POSIX_V6_ILP32_OFF32_LIBS | 7298 _CS_POSIX_V6_ILP32_OFF32_LINTFLAGS | 7299 _CS_POSIX_V6_ILP32_OFFBIG_CFLAGS | 7300 _CS_POSIX_V6_ILP32_OFFBIG_LDFLAGS | 7301 _CS_POSIX_V6_ILP32_OFFBIG_LIBS | 7302 _CS_POSIX_V6_ILP32_OFFBIG_LINTFLAGS | 7303 _CS_POSIX_V6_LP64_OFF64_CFLAGS | 7304 _CS_POSIX_V6_LP64_OFF64_LDFLAGS | 7305 _CS_POSIX_V6_LP64_OFF64_LIBS | 7306 _CS_POSIX_V6_LP64_OFF64_LINTFLAGS | 7307 _CS_POSIX_V6_LPBIG_OFFBIG_CFLAGS | 7308 _CS_POSIX_V6_LPBIG_OFFBIG_LDFLAGS | 7309 _CS_POSIX_V6_LPBIG_OFFBIG_LIBS | 7310 _CS_POSIX_V6_LPBIG_OFFBIG_LINTFLAGS | 7311 XSI _CS_XBS5_ILP32_OFF32_CFLAGS (LEGACY) | 7312 _CS_XBS5_ILP32_OFF32_LDFLAGS (LEGACY) | 7313 _CS_XBS5_ILP32_OFF32_LIBS (LEGACY) | 7314 _CS_XBS5_ILP32_OFF32_LINTFLAGS (LEGACY) | 7315 _CS_XBS5_ILP32_OFFBIG_CFLAGS (LEGACY) | 7316 _CS_XBS5_ILP32_OFFBIG_LDFLAGS (LEGACY) | 7317 _CS_XBS5_ILP32_OFFBIG_LIBS (LEGACY) | 7318 _CS_XBS5_ILP32_OFFBIG_LINTFLAGS (LEGACY) | 7319 _CS_XBS5_LP64_OFF64_CFLAGS (LEGACY) | 7320 _CS_XBS5_LP64_OFF64_LDFLAGS (LEGACY) | 7321 _CS_XBS5_LP64_OFF64_LIBS (LEGACY) | 7322 _CS_XBS5_LP64_OFF64_LINTFLAGS (LEGACY) | 7323 _CS_XBS5_LPBIG_OFFBIG_CFLAGS (LEGACY) | 7324 _CS_XBS5_LPBIG_OFFBIG_LDFLAGS (LEGACY) | 7325 _CS_XBS5_LPBIG_OFFBIG_LIBS (LEGACY) | 7326 _CS_XBS5_LPBIG_OFFBIG_LINTFLAGS (LEGACY) | 7327 | 7328 If len is not 0, and if name has a configuration-defined value, confstr( ) shall copy that value into 7329 the len-byte buffer pointed to by buf. If the string to be returned is longer than len bytes, 7330 including the terminating null, then confstr( ) shall truncate the string to len-1 bytes and null- 7331 terminate the result. The application can detect that the string was truncated by comparing the 714 Technical Standard (2000) (Draft July 31, 2000) System Interfaces confstr( ) 7332 value returned by confstr( ) with len. 7333 If len is 0 and buf is a null pointer, then confstr( ) shall still return the integer value as defined 7334 below, but shall not return a string. If len is 0 but buf is not a null pointer, the result is 7335 unspecified. 7336 If the implementation supports the Shell option, the string stored in buf after a call to: | 7337 confstr(_CS_PATH, buf, sizeof(buf)) 7338 can be used as a value of the PATH environment variable that accesses all of the standard 7339 utilities of IEEE Std. 1003.1-200x, if the return value is less than or equal to sizeof(buf). 7340 RETURN VALUE 7341 If name has a configuration-defined value, confstr( ) shall return the size of buffer that would be 7342 needed to hold the entire configuration-defined value including the terminating null. If this 7343 return value is greater than len, the string returned in buf is truncated. 7344 If name is invalid, confstr( ) shall return 0 and set errno to indicate the error. 7345 If name does not have a configuration-defined value, confstr( ) shall return 0 and leave errno 7346 unchanged. 7347 ERRORS 7348 The confstr( ) function shall fail if: 7349 [EINVAL] The value of the name argument is invalid. | 7350 EXAMPLES 7351 None. 7352 APPLICATION USAGE 7353 An application can distinguish between an invalid name parameter value and one that 7354 corresponds to a configurable variable that has no configuration-defined value by checking if 7355 errno is modified. This mirrors the behavior of sysconf( ). 7356 The original need for this function was to provide a way of finding the configuration-defined 7357 default value for the environment variable PATH. Since PATH can be modified by the user to 7358 include directories that could contain utilities replacing the standard utilities in the Shell and | 7359 Utilities volume of IEEE Std. 1003.1-200x, applications need a way to determine the system- | 7360 supplied PATH environment variable value that contains the correct search path for the standard 7361 utilities. 7362 An application could use: 7363 confstr(name, (char *)NULL, (size_t)0) 7364 to find out how big a buffer is needed for the string value; use malloc( ) to allocate a buffer to 7365 hold the string; and call confstr( ) again to get the string. Alternately, it could allocate a fixed, 7366 static buffer that is big enough to hold most answers (perhaps 512 or 1 024 bytes), but then use 7367 malloc( ) to allocate a larger buffer if it finds that this is too small. 7368 RATIONALE 7369 Application developers can normally determine any configuration variable by means of reading 7370 from the stream opened by a call to: 7371 popen("command -p getconf variable", "r"); 7372 The confstr( ) function with a name argument of _CS_PATH returns a string that can be used as a 7373 PATH environment variable setting that will reference the standard shell and utilities as | 7374 described in the Shell and Utilities volume of IEEE Std. 1003.1-200x. | System Interfaces, Issue 6 715 confstr( ) System Interfaces 7375 The confstr( ) function copies the returned string into a buffer supplied by the application instead 7376 of returning a pointer to a string. This allows a cleaner function in some implementations (such 7377 as those with lightweight threads) and resolves questions about when the application must copy | 7378 the string returned. 7379 FUTURE DIRECTIONS 7380 None. 7381 SEE ALSO 7382 pathconf( ), sysconf( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , the Shell | 7383 and Utilities volume of IEEE Std. 1003.1-200x, c99 | 7384 CHANGE HISTORY 7385 First released in Issue 4. Derived from the ISO POSIX-2 standard. | 7386 Issue 5 7387 A table indicating the permissible values of name are added to the DESCRIPTION. All those 7388 marked EX are new in this issue. 7389 Issue 6 7390 The Open Group corrigenda item U033/7 has been applied. The return value for the case 7391 returning the size of the buffer now explicitly states that this includes the terminating null. 7392 The following new requirements on POSIX implementations derive from alignment with the 7393 Single UNIX Specification: 7394 * The DESCRIPTION is updated with new arguments which can be used to determine 7395 configuration strings for C compiler flags, linker/loader flags, and libraries for each different 7396 supported programming environment. This is a change to support data size neutrality. 7397 The following changes were made to align with the IEEE P1003.1a draft standard: 7398 * The DESCRIPTION is updated to include text describing how _CS_PATH can be used to 7399 obtain a PATH to access the standard utilities. 7400 The macros associated with the c89 programming models are marked LEGACY and new || 7401 equivalent macros associated with c99 are introduced. | 716 Technical Standard (2000) (Draft July 31, 2000) System Interfaces conj( ) 7402 NAME | 7403 conj, conjf, conjl - complex conjugate functions | 7404 SYNOPSIS | 7405 #include | 7406 double complex conj(double complex z); | 7407 float complex conjf(float complex z); | 7408 long double complex conjl(long double complex z); | 7409 DESCRIPTION | 7410 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 7411 conflict between the requirements described here and the ISO C standard is unintentional. This | 7412 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 7413 These functions shall compute the complex conjugate of z, by reversing the sign of its imaginary | 7414 part. | 7415 RETURN VALUE | 7416 These functions return the complex conjugate value. | 7417 ERRORS | 7418 No errors are defined. | 7419 EXAMPLES | 7420 None. | 7421 APPLICATION USAGE | 7422 None. | 7423 RATIONALE | 7424 None. | 7425 FUTURE DIRECTIONS | 7426 None. | 7427 SEE ALSO | 7428 carg( ), cimag( ), cproj( ), creal( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 7429 | 7430 CHANGE HISTORY || 7431 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 717 connect( ) System Interfaces 7432 NAME 7433 connect - connect a socket 7434 SYNOPSIS 7435 #include 7436 int connect(int socket, const struct sockaddr *address, 7437 socklen_t address_len); 7438 DESCRIPTION 7439 The connect( ) function requests a connection to be made on a socket. The function takes the 7440 following arguments: 7441 socket Specifies the file descriptor associated with the socket. 7442 address Points to a sockaddr structure containing the peer address. The length and 7443 format of the address depend on the address family of the socket. 7444 address_len Specifies the length of the sockaddr structure pointed to by the address 7445 argument. 7446 If the socket has not already been bound to a local address, connect( ) shall bind it to an address 7447 which, unless the socket's address family is AF_UNIX, is an unused local address. 7448 If the initiating socket is not connection-mode, then connect( ) shall set the socket's peer address, 7449 and no connection is made. For SOCK_DGRAM sockets, the peer address identifies where all 7450 datagrams are sent on subsequent send( ) functions, and limits the remote sender for subsequent 7451 recv( ) functions. If address is a null address for the protocol, the socket's peer address shall be 7452 reset. 7453 If the initiating socket is connection-mode, then connect( ) attempts to establish a connection to 7454 the address specified by the address argument. 7455 If the connection cannot be established immediately and O_NONBLOCK is not set for the file 7456 descriptor for the socket, connect( ) shall block for up to an unspecified timeout interval until the 7457 connection is established. If the timeout interval expires before the connection is established, 7458 connect( ) shall fail and the connection attempt shall be aborted. If connect( ) is interrupted by a 7459 signal that is caught while blocked waiting to establish a connection, connect( ) shall fail and set 7460 errno to [EINTR], but the connection request shall not be aborted, and the connection shall be 7461 established asynchronously. 7462 If the connection cannot be established immediately and O_NONBLOCK is set for the file 7463 descriptor for the socket, connect( ) shall fail and set errno to [EINPROGRESS], but the connection 7464 request shall not be aborted, and the connection shall be established asynchronously. 7465 Subsequent calls to connect( ) for the same socket, before the connection is established, shall fail 7466 and set errno to [EALREADY]. 7467 When the connection has been established asynchronously, select( ) and poll( ) shall indicate that 7468 the file descriptor for the socket is ready for writing. 7469 The socket in use may require the process to have appropriate privileges to use the connect( ) 7470 function. 7471 RETURN VALUE 7472 Upon successful completion, connect( ) shall return 0; otherwise, -1 shall be returned and errno 7473 set to indicate the error. 718 Technical Standard (2000) (Draft July 31, 2000) System Interfaces connect( ) 7474 ERRORS 7475 The connect( ) function shall fail if: 7476 [EADDRNOTAVAIL] 7477 The specified address is not available from the local machine. 7478 [EAFNOSUPPORT] 7479 The specified address is not a valid address for the address family of the 7480 specified socket. 7481 [EALREADY] A connection request is already in progress for the specified socket. 7482 [EBADF] The socket argument is not a valid file descriptor. 7483 [ECONNREFUSED] 7484 The target address was not listening for connections or refused the connection 7485 request. | 7486 [EINPROGRESS] O_NONBLOCK is set for the file descriptor for the socket and the connection 7487 cannot be immediately established; the connection shall be established 7488 asynchronously. 7489 [EINTR] The attempt to establish a connection was interrupted by delivery of a signal 7490 that was caught; the connection shall be established asynchronously. 7491 [EISCONN] The specified socket is connection-mode and is already connected. 7492 [ENETUNREACH] 7493 No route to the network is present. 7494 [ENOTSOCK] The socket argument does not refer to a socket. 7495 [EPROTOTYPE] The specified address has a different type than the socket bound to the 7496 specified peer address. 7497 [ETIMEDOUT] The attempt to connect timed out before a connection was made. 7498 If the address family of the socket is AF_UNIX, then connect( ) shall fail if: 7499 [EIO] An I/O error occurred while reading from or writing to the file system. 7500 [ELOOP] A loop exists in symbolic links encountered during resolution of the path | 7501 name in address. | 7502 [ENAMETOOLONG] 7503 A component of a path name exceeded {NAME_MAX} characters, or an entire 7504 path name exceeded {PATH_MAX} characters. 7505 [ENOENT] A component of the path name does not name an existing file or the path 7506 name is an empty string. 7507 [ENOTDIR] A component of the path prefix of the path name in address is not a directory. 7508 The connect( ) function may fail if: 7509 [EACCES] Search permission is denied for a component of the path prefix; or write 7510 access to the named socket is denied. 7511 [EADDRINUSE] Attempt to establish a connection that uses addresses that are already in use. 7512 [ECONNRESET] Remote host reset the connection request. 7513 [EHOSTUNREACH] 7514 The destination host cannot be reached (probably because the host is down or System Interfaces, Issue 6 719 connect( ) System Interfaces 7515 a remote router cannot reach it). 7516 [EINVAL] The address_len argument is not a valid length for the address family; or 7517 invalid address family in the sockaddr structure. | 7518 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during | 7519 resolution of the path name in address. | 7520 [ENAMETOOLONG] 7521 Path name resolution of a symbolic link produced an intermediate result 7522 whose length exceeds {PATH_MAX}. 7523 [ENETDOWN] The local network interface used to reach the destination is down. | 7524 [ENOBUFS] No buffer space is available. | 7525 [EOPNOTSUPP] The socket is listening and cannot be connected. 7526 EXAMPLES 7527 None. 7528 APPLICATION USAGE 7529 If connect( ) fails, the state of the socket is unspecified. Portable applications should close the file 7530 descriptor and create a new socket before attempting to reconnect. 7531 RATIONALE 7532 None. 7533 FUTURE DIRECTIONS 7534 None. 7535 SEE ALSO 7536 accept( ), bind( ), close( ), getsockname( ), poll( ), select( ), send( ), shutdown( ), socket( ), the Base | 7537 Definitions volume of IEEE Std. 1003.1-200x, | 7538 CHANGE HISTORY 7539 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. | 7540 The wording of the mandatory [ELOOP] error condition is updated, and a second optional || 7541 [ELOOP] error condition is added. | 720 Technical Standard (2000) (Draft July 31, 2000) System Interfaces copysign( ) 7542 NAME | 7543 copysign, copysignf, copysignl - number manipulation function | 7544 SYNOPSIS | 7545 #include | 7546 double copysign(double x, double y); | 7547 float copysignf(float x, float y); | 7548 long double copysignl(long double x, long double y); | 7549 DESCRIPTION | 7550 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 7551 conflict between the requirements described here and the ISO C standard is unintentional. This | 7552 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 7553 These functions shall produce a value with the magnitude of x and the sign of y. They produce a | 7554 NaN (with the sign of y) if x is a NaN. On implementations that represent a signed zero but do | 7555 not treat negative zero consistently in arithmetic operations, these functions regard the sign of | 7556 zero as positive. | 7557 An application wishing to check for error situations should set errno to 0 before calling these | 7558 functions. If errno is non-zero on return, or the return value is NaN, an error has occurred. | 7559 RETURN VALUE | 7560 Upon successful completion, these functions shall return a value with the magnitude of x and | 7561 the sign of y. | 7562 If x is ±Inf, these functions shall return x. | 7563 If x is NaN, NaN shall be returned and errno may be set to [EDOM]. | 7564 ERRORS | 7565 These functions may fail if: | 7566 [EDOM] The value of x is NaN. | 7567 EXAMPLES | 7568 None. | 7569 APPLICATION USAGE | 7570 None. | 7571 RATIONALE | 7572 copysign( ) and signbit( ) need not be consistent with each other if the arithmetic is not consistent | 7573 in its treatment of zeros. For example, the IBM S/370 has instructions to flip the sign bit making | 7574 it possible to create a negative zero, but ±0.0 x ±1.0 is always +0.0. In this case, copysign( ) will | 7575 treat 0.0 as positive, while signbit( ) will treat it as negative. | 7576 FUTURE DIRECTIONS | 7577 None. | 7578 SEE ALSO | 7579 signbit( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 7580 CHANGE HISTORY || 7581 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 721 cos( ) System Interfaces 7582 NAME 7583 cos, cosf, cosl - cosine function | 7584 SYNOPSIS 7585 #include 7586 double cos(double x); 7587 float cosf(float x); | 7588 long double cosl(long double x); | 7589 DESCRIPTION | 7590 CX The functionality described on this reference page is aligned with the ISO C standard. Any 7591 conflict between the requirements described here and the ISO C standard is unintentional. This 7592 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 7593 These functions shall compute the cosine of x, measured in radians. | 7594 An application wishing to check for error situations should set errno to 0 before calling cos( ). If 7595 errno is non-zero on return, or the returned value is NaN, an error has occurred. 7596 RETURN VALUE 7597 Upon successful completion, these functions shall return the cosine of x. | 7598 XSI If x is NaN, NaN shall be returned and errno may be set to [EDOM]. | 7599 XSI If x is ±Inf, either 0 shall be returned and errno set to [EDOM], or NaN shall be returned and errno 7600 may be set to [EDOM]. 7601 If the result underflows, 0 shall be returned and errno may be set to [ERANGE]. | 7602 ERRORS 7603 These functions may fail if: | 7604 XSI [EDOM] The value of x is NaN or x is ±Inf. | 7605 [ERANGE] The result underflows | 7606 XSI No other errors shall occur. 7607 EXAMPLES 7608 Taking the Cosine of a 45-Degree Angle 7609 #include 7610 ... 7611 double radians = 45 * M_PI / 180; 7612 double result; 7613 ... 7614 result = cos(radians); 7615 APPLICATION USAGE 7616 The cos( ) function may lose accuracy when its argument is far from 0. 7617 RATIONALE 7618 None. 7619 FUTURE DIRECTIONS 7620 None. 722 Technical Standard (2000) (Draft July 31, 2000) System Interfaces cos( ) 7621 SEE ALSO 7622 acos( ), isnan( ), sin( ), tan( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 7623 CHANGE HISTORY 7624 First released in Issue 1. Derived from Issue 1 of the SVID. | 7625 Issue 4 7626 References to matherr( ) are removed. 7627 The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 7628 ISO C standard and to rationalize error handling in the mathematics functions. 7629 The return value specified for [EDOM] is marked as an extension. 7630 Issue 5 7631 The DESCRIPTION is updated to indicate how an application should check for an error. This 7632 text was previously published in the APPLICATION USAGE section. | 7633 Issue 6 | 7634 The cosf( ) and cosl( ) functions are added for alignment with the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 723 cosh( ) System Interfaces 7635 NAME 7636 cosh, coshf, coshl - hyperbolic cosine function | 7637 SYNOPSIS 7638 #include 7639 double cosh(double x); 7640 float coshf(float x); | 7641 long double coshl(long double x); | 7642 DESCRIPTION | 7643 CX The functionality described on this reference page is aligned with the ISO C standard. Any 7644 conflict between the requirements described here and the ISO C standard is unintentional. This 7645 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 7646 These functions shall compute the hyperbolic cosine of x. | 7647 An application wishing to check for error situations should set errno to 0 before calling cosh( ). If 7648 errno is non-zero on return, or the returned value is NaN, an error has occurred. 7649 RETURN VALUE 7650 Upon successful completion, these functions shall return the hyperbolic cosine of x. | 7651 If the result would cause an overflow, HUGE_VAL shall be returned and errno set to [ERANGE]. | 7652 XSI If x is NaN, NaN shall be returned and errno may be set to [EDOM]. | 7653 ERRORS 7654 These functions shall fail if: | 7655 [ERANGE] The result would cause an overflow. | 7656 These functions may fail if: | 7657 XSI [EDOM] The value of x is NaN. 7658 XSI No other errors shall occur. 7659 EXAMPLES 7660 None. 7661 APPLICATION USAGE 7662 None. 7663 RATIONALE 7664 None. 7665 FUTURE DIRECTIONS 7666 None. 7667 SEE ALSO 7668 acosh( ), isnan( ), sinh( ), tanh( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 7669 CHANGE HISTORY 7670 First released in Issue 1. Derived from Issue 1 of the SVID. | 7671 Issue 4 7672 References to matherr( ) are removed. 7673 The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 7674 ISO C standard and to rationalize error handling in the mathematics functions. 724 Technical Standard (2000) (Draft July 31, 2000) System Interfaces cosh( ) 7675 The return value specified for [EDOM] is marked as an extension. 7676 Issue 5 7677 The DESCRIPTION is updated to indicate how an application should check for an error. This 7678 text was previously published in the APPLICATION USAGE section. | 7679 Issue 6 || 7680 The coshf( ) and coshl( ) functions are added for alignment with the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 725 cpow( ) System Interfaces 7681 NAME | 7682 cpow, cpowf, cpowl - complex power functions | 7683 SYNOPSIS | 7684 #include | 7685 double complex cpow(double complex x, double complex y); | 7686 float complex cpowf(float complex x, float complex y); | 7687 long double complex cpowl(long double complex x, | 7688 long double complex y); | 7689 DESCRIPTION | 7690 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 7691 conflict between the requirements described here and the ISO C standard is unintentional. This | 7692 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 7693 These functions shall compute the complex power function xy, with a branch cut for the first | 7694 parameter along the negative real axis. | 7695 RETURN VALUE | 7696 These functions shall return the complex power function value. | 7697 ERRORS | 7698 No errors are defined. | 7699 EXAMPLES | 7700 None. | 7701 APPLICATION USAGE | 7702 None. | 7703 RATIONALE | 7704 None. | 7705 FUTURE DIRECTIONS | 7706 None. | 7707 SEE ALSO | 7708 cabs( ), csqrt( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 7709 CHANGE HISTORY || 7710 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | 726 Technical Standard (2000) (Draft July 31, 2000) System Interfaces cproj( ) 7711 NAME | 7712 cproj, cprojf, cprojl - complex projection functions | 7713 SYNOPSIS | 7714 #include | 7715 double complex cproj(double complex z); | 7716 float complex cprojf(float complex z); | 7717 long double complex cprojl(long double complex z); | 7718 DESCRIPTION | 7719 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 7720 conflict between the requirements described here and the ISO C standard is unintentional. This | 7721 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 7722 These functions shall compute a projection of z onto the Riemann sphere: z projects to z, except | 7723 that all complex infinities (even those with one infinite part and one NaN part) project to | 7724 positive infinity on the real axis. If z has an infinite part, then cproj(z) is equivalent to: | 7725 INFINITY + I * copysign(0.0, cimag(z)) | 7726 RETURN VALUE | 7727 These functions shall return the value of the projection onto the Riemann sphere. | 7728 ERRORS | 7729 No errors are defined. | 7730 EXAMPLES | 7731 None. | 7732 APPLICATION USAGE | 7733 None. | 7734 RATIONALE | 7735 Two topologies are commonly used in complex mathematics: the complex plane with its | 7736 continuum of infinities, and the Riemann sphere with its single infinity. The complex plane is | 7737 better suited for transcendental functions, the Riemann sphere for algebraic functions. The | 7738 complex types with their multiplicity of infinities provide a useful (though imperfect) model for | 7739 the complex plane. The cproj( ) function helps model the Riemann sphere by mapping all | 7740 infinities to one, and should be used just before any operation, especially comparisons, that | 7741 might give spurious results for any of the other infinities. Note that a complex value with one | 7742 infinite part and one NaN part is regarded as an infinity, not a NaN, because if one part is | 7743 infinite, the complex value is infinite independent of the value of the other part. For the same | 7744 reason, cabs( ) returns an infinity if its argument has an infinite part and a NaN part. | 7745 FUTURE DIRECTIONS | 7746 None. | 7747 SEE ALSO | 7748 carg( ), cimag( ), conj( ), creal( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 7749 | 7750 CHANGE HISTORY || 7751 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 727 creal( ) System Interfaces 7752 NAME | 7753 creal, crealf, creall - complex real functions | 7754 SYNOPSIS | 7755 #include | 7756 double creal(double complex z); | 7757 float crealf(float complex z); | 7758 long double creall(long double complex z); | 7759 DESCRIPTION | 7760 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 7761 conflict between the requirements described here and the ISO C standard is unintentional. This | 7762 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 7763 These functions shall compute the real part of z. | 7764 RETURN VALUE | 7765 These functions shall return the real part value. | 7766 ERRORS | 7767 No errors are defined. | 7768 EXAMPLES | 7769 None. | 7770 APPLICATION USAGE | 7771 For a variable z of complex type: | 7772 z == creal(z) + cimag(z)*I | 7773 RATIONALE | 7774 None. | 7775 FUTURE DIRECTIONS | 7776 None. | 7777 SEE ALSO | 7778 carg( ), cimag( ), conj( ), cproj( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 7779 | 7780 CHANGE HISTORY || 7781 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | 728 Technical Standard (2000) (Draft July 31, 2000) System Interfaces creat( ) 7782 NAME 7783 creat - create a new file or rewrite an existing one 7784 SYNOPSIS 7785 OH #include 7786 #include 7787 int creat(const char *path, mode_t mode); 7788 DESCRIPTION 7789 The function call: 7790 creat(path, mode) 7791 is equivalent to: 7792 open(path, O_WRONLY|O_CREAT|O_TRUNC, mode) 7793 RETURN VALUE 7794 Refer to open( ). 7795 ERRORS 7796 Refer to open( ). 7797 EXAMPLES 7798 Creating a File 7799 The following example creates the file /tmp/file with read and write permissions for the file 7800 owner and read permission for group and others. The resulting file descriptor is assigned to the 7801 fd variable. 7802 #include 7803 ... 7804 int fd; 7805 mode_t mode = S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH; 7806 char *filename = "/tmp/file"; 7807 ... 7808 fd = creat(filename, mode); 7809 ... 7810 APPLICATION USAGE 7811 None. 7812 RATIONALE 7813 The creat( ) function is redundant. Its services are also provided by the open( ) function. It has 7814 been included primarily for historical purposes since many existing applications depend on it. It 7815 is best considered a part of the C binding rather than a function that should be provided in other 7816 languages. 7817 FUTURE DIRECTIONS 7818 None. 7819 SEE ALSO 7820 open( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , , | 7821 System Interfaces, Issue 6 729 creat( ) System Interfaces 7822 CHANGE HISTORY 7823 First released in Issue 1. Derived from Issue 1 of the SVID. | 7824 Issue 4 7825 The and headers are now marked as optional (OH); these headers 7826 need not be included on XSI-conformant systems. 7827 The following change is incorporated for alignment with the ISO POSIX-1 standard: 7828 * The type of argument path is changed from char* to const char*. 7829 Issue 6 7830 In the SYNOPSIS, the inclusion of is no longer required. 7831 The following new requirements on POSIX implementations derive from alignment with the 7832 Single UNIX Specification: 7833 * The requirement to include has been removed. Although was 7834 required for conforming implementations of previous POSIX specifications, it was not 7835 required for UNIX applications. 730 Technical Standard (2000) (Draft July 31, 2000) System Interfaces crypt( ) 7836 NAME 7837 crypt - string encoding function (CRYPT) 7838 SYNOPSIS 7839 XSI #include 7840 char *crypt(const char *key, const char *salt); | 7841 | 7842 DESCRIPTION 7843 The crypt( ) function is a string encoding function. The algorithm is implementation-defined. | 7844 The key argument points to a string to be encoded. The salt argument is a string chosen from the 7845 set: 7846 a b c d e f g h i j k l m n o p q r s t u v w x y z 7847 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 7848 0 1 2 3 4 5 6 7 8 9 . / 7849 The first two characters of this string may be used to perturb the encoding algorithm. 7850 The return value of crypt( ) points to static data that is overwritten by each call. 7851 The crypt( ) function need not be reentrant. A function that is not required to be reentrant is not 7852 required to be thread-safe. 7853 RETURN VALUE 7854 Upon successful completion, crypt( ) shall return a pointer to the encoded string. The first two 7855 characters of the returned value are those of the salt argument. Otherwise, it shall return a null 7856 pointer and set errno to indicate the error. 7857 ERRORS 7858 The crypt( ) function shall fail if: 7859 [ENOSYS] The functionality is not supported on this implementation. | 7860 EXAMPLES 7861 Encoding Passwords 7862 The following example finds a user database entry matching a particular user name and changes 7863 the current password to a new password. The crypt( ) function is used to generate an encoded 7864 version of each password. The first call to crypt( ) produces an encoded version of the old 7865 password; that encoded password is then compared to the password stored in the user database. 7866 The second call to crypt( ) encodes the new password before it is stored. 7867 The putpwent( ) function, used in the following example, is not part of IEEE Std. 1003.1-200x. 7868 #include 7869 #include 7870 #include 7871 #include 7872 ... 7873 int valid_change; 7874 int pfd; /* Integer for file descriptor returned by open(). */ 7875 FILE *fpfd; /* File pointer for use in putpwent(). */ 7876 struct passwd *p; 7877 char user[100]; 7878 char oldpasswd[100]; 7879 char newpasswd[100]; System Interfaces, Issue 6 731 crypt( ) System Interfaces 7880 char savepasswd[100]; 7881 ... 7882 valid_change = 0; 7883 while ((p = getpwent()) != NULL) { 7884 /* Change entry if found. */ 7885 if (strcmp(p->pw_name, user) == 0) { 7886 if (strcmp(p->pw_passwd, crypt(oldpasswd, p->pw_passwd)) == 0) { 7887 strcpy(savepasswd, crypt(newpasswd, user)); 7888 p->pw_passwd = savepasswd; 7889 valid_change = 1; 7890 } 7891 else { 7892 fprintf(stderr, "Old password is not valid\n"); 7893 } 7894 } 7895 /* Put passwd entry into ptmp. */ 7896 putpwent(p, fpfd); 7897 } 7898 APPLICATION USAGE 7899 The values returned by this function need not be portable among XSI-conformant systems. 7900 RATIONALE 7901 None. 7902 FUTURE DIRECTIONS 7903 None. 7904 SEE ALSO 7905 encrypt( ), setkey( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 7906 CHANGE HISTORY 7907 First released in Issue 1. Derived from Issue 1 of the SVID. | 7908 Issue 4 7909 The header is added to the SYNOPSIS section. 7910 The type of arguments key and salt are changed from char* to const char*. 7911 The DESCRIPTION now explicitly defines the characters that can appear in the salt argument. 7912 Issue 5 7913 Normative text previously in the APPLICATION USAGE section is moved to the | 7914 DESCRIPTION. 732 Technical Standard (2000) (Draft July 31, 2000) System Interfaces csin( ) 7915 NAME | 7916 csin, csinf, csinl - complex sine functions | 7917 SYNOPSIS | 7918 #include | 7919 double complex csin(double complex z); | 7920 float complex csinf(float complex z); | 7921 long double complex csinl(long double complex z); | 7922 DESCRIPTION | 7923 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 7924 conflict between the requirements described here and the ISO C standard is unintentional. This | 7925 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 7926 These functions shall compute the complex sine of z. | 7927 RETURN VALUE | 7928 These functions shall return the complex sine value. | 7929 ERRORS | 7930 No errors are defined. | 7931 EXAMPLES | 7932 None. | 7933 APPLICATION USAGE | 7934 None. | 7935 RATIONALE | 7936 None. | 7937 FUTURE DIRECTIONS | 7938 None. | 7939 SEE ALSO | 7940 casin( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 7941 CHANGE HISTORY || 7942 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 733 csinh( ) System Interfaces 7943 NAME | 7944 csinh, csinhf, csinhl - complex hyperbolic sine functions | 7945 SYNOPSIS | 7946 #include | 7947 double complex csinh(double complex z); | 7948 float complex csinhf(float complex z); | 7949 long double complex csinhl(long double complex z); | 7950 DESCRIPTION | 7951 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 7952 conflict between the requirements described here and the ISO C standard is unintentional. This | 7953 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 7954 These functions shall compute the complex hyperbolic sine of z. | 7955 RETURN VALUE | 7956 These functions shall return the complex hyperbolic sine value. | 7957 ERRORS | 7958 No errors are defined. | 7959 EXAMPLES | 7960 None. | 7961 APPLICATION USAGE | 7962 None. | 7963 RATIONALE | 7964 None. | 7965 FUTURE DIRECTIONS | 7966 None. | 7967 SEE ALSO | 7968 casinh( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 7969 CHANGE HISTORY || 7970 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | 734 Technical Standard (2000) (Draft July 31, 2000) System Interfaces csqrt( ) 7971 NAME | 7972 csqrt, csqrtf, csqrtl - complex square root functions | 7973 SYNOPSIS | 7974 #include | 7975 double complex csqrt(double complex z); | 7976 float complex csqrtf(float complex z); | 7977 long double complex csqrtl(long double complex z); | 7978 DESCRIPTION | 7979 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 7980 conflict between the requirements described here and the ISO C standard is unintentional. This | 7981 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 7982 These functions shall compute the complex square root of z, with a branch cut along the | 7983 negative real axis. | 7984 RETURN VALUE | 7985 These functions shall return the complex square root value, in the range of the right half-plane | 7986 (including the imaginary axis). | 7987 ERRORS | 7988 No errors are defined. | 7989 EXAMPLES | 7990 None. | 7991 APPLICATION USAGE | 7992 None. | 7993 RATIONALE | 7994 None. | 7995 FUTURE DIRECTIONS | 7996 None. | 7997 SEE ALSO | 7998 cabs( ), cpow( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 7999 CHANGE HISTORY || 8000 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 735 ctan( ) System Interfaces 8001 NAME | 8002 ctan, ctanf, ctanl - complex tangent functions | 8003 SYNOPSIS | 8004 #include | 8005 double complex ctan(double complex z); | 8006 float complex ctanf(float complex z); | 8007 long double complex ctanl(long double complex z); | 8008 DESCRIPTION | 8009 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 8010 conflict between the requirements described here and the ISO C standard is unintentional. This | 8011 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 8012 These functions shall compute the complex tangent of z. | 8013 RETURN VALUE | 8014 These functions shall return the complex tangent value. | 8015 ERRORS | 8016 No errors are defined. | 8017 EXAMPLES | 8018 None. | 8019 APPLICATION USAGE | 8020 None. | 8021 RATIONALE | 8022 None. | 8023 FUTURE DIRECTIONS | 8024 None. | 8025 SEE ALSO | 8026 catan( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 8027 CHANGE HISTORY || 8028 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | 736 Technical Standard (2000) (Draft July 31, 2000) System Interfaces ctanh( ) 8029 NAME | 8030 ctanh, ctanhf, ctanhl - complex hyperbolic tangent functions | 8031 SYNOPSIS | 8032 #include | 8033 double complex ctanh(double complex z); | 8034 float complex ctanhf(float complex z); | 8035 long double complex ctanhl(long double complex z); | 8036 DESCRIPTION | 8037 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 8038 conflict between the requirements described here and the ISO C standard is unintentional. This | 8039 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 8040 These functions shall compute the complex hyperbolic tangent of z. | 8041 RETURN VALUE | 8042 These functions shall return the complex hyperbolic tangent value. | 8043 ERRORS | 8044 No errors are defined. | 8045 EXAMPLES | 8046 None. | 8047 APPLICATION USAGE | 8048 None. | 8049 RATIONALE | 8050 None. | 8051 FUTURE DIRECTIONS | 8052 None. | 8053 SEE ALSO | 8054 catanh( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 8055 CHANGE HISTORY || 8056 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 737 ctermid( ) System Interfaces 8057 NAME 8058 ctermid - generate a path name for controlling terminal 8059 SYNOPSIS 8060 #include 8061 char *ctermid(char *s); 8062 DESCRIPTION 8063 The ctermid( ) function shall generate a string that, when used as a path name, refers to the 8064 current controlling terminal for the current process. If ctermid( ) returns a path name, access to 8065 the file is not guaranteed. 8066 If the application uses any of the _POSIX_THREAD_SAFE_FUNCTIONS or _POSIX_THREADS 8067 functions, it shall ensure that the ctermid( ) function is called with a non-NULL parameter. 8068 RETURN VALUE 8069 If s is a null pointer, the string is generated in an area that may be static (and therefore may be 8070 overwritten by each call), the address of which shall be returned. Otherwise, s is assumed to | 8071 point to a character array of at least {L_ctermid} bytes; the string is placed in this array and the | 8072 value of s shall be returned. The symbolic constant {L_ctermid} is defined in , and shall | 8073 have a value greater than 0. 8074 The ctermid( ) function shall return an empty string if the path name that would refer to the 8075 controlling terminal cannot be determined, or if the function is unsuccessful. 8076 ERRORS 8077 No errors are defined. 8078 EXAMPLES 8079 Determining the Controlling Terminal for the Current Process 8080 The following example returns a pointer to a string that identifies the controlling terminal for the 8081 current process. The path name for the terminal is stored in the array pointed to by the ptr | 8082 argument, which has a size of {L_ctermid} bytes, as indicated by the term argument. | 8083 #include 8084 ... 8085 char term[L_ctermid]; 8086 char *ptr; 8087 ptr = ctermid(term); 8088 APPLICATION USAGE 8089 The difference between ctermid( ) and ttyname( ) is that ttyname( ) must be handed a file 8090 descriptor and return a path of the terminal associated with that file descriptor, while ctermid( ) 8091 returns a string (such as "/dev/tty") that refers to the current controlling terminal if used as a 8092 path name. 8093 RATIONALE 8094 {L_ctermid} must be defined appropriately for a given implementation and must be greater than | 8095 zero so that array declarations using it are accepted by the compiler. The value includes the 8096 terminating null byte. 8097 Portable applications that use threads cannot call ctermid( ) with NULL as the parameter if either 8098 _POSIX_THREAD_SAFE_FUNCTIONS or _POSIX_THREADS is defined. If s is not NULL, the 8099 ctermid( ) function generates a string that, when used as a path name, refers to the current 8100 controlling terminal for the current process. If s is NULL, the return value of ctermid( ) is 738 Technical Standard (2000) (Draft July 31, 2000) System Interfaces ctermid( ) 8101 undefined. 8102 If the ctermid( ) function returns a path name, access to the file is not guaranteed. 8103 There is no additional burden on the programmer-changing to use a hypothetical thread-safe 8104 version of ctermid( ) along with allocating a buffer is more of a burden than merely allocating a 8105 buffer. Application code should not assume that the returned string is short, as some 8106 implementations have more than two path name components before reaching a logical device 8107 name. 8108 FUTURE DIRECTIONS 8109 None. 8110 SEE ALSO 8111 ttyname( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 8112 CHANGE HISTORY 8113 First released in Issue 1. Derived from Issue 1 of the SVID. | 8114 Issue 4 8115 The following change is incorporated for alignment with the ISO POSIX-1 standard: 8116 * The DESCRIPTION and RETURN VALUE sections, though functionally identical to Issue 3, 8117 are rewritten. 8118 Issue 5 8119 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 8120 Issue 6 8121 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 739 ctime( ) System Interfaces 8122 NAME 8123 ctime, ctime_r - convert a time value to date and time string 8124 SYNOPSIS 8125 #include 8126 char *ctime(const time_t *clock); 8127 TSF char *ctime_r(const time_t *clock, char *buf); 8128 8129 DESCRIPTION 8130 CX The functionality described on this reference page is aligned with the ISO C standard. Any 8131 conflict between the requirements described here and the ISO C standard is unintentional. This 8132 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 8133 The ctime( ) function shall convert the time pointed to by clock, representing time in seconds 8134 since the Epoch, to local time in the form of a string. It is equivalent to: 8135 asctime(localtime(clock)) 8136 CX The asctime( ), ctime( ), gmtime( ), and localtime( ) functions return values in one of two static 8137 objects: a broken-down time structure and an array of char. Execution of any of the functions 8138 may overwrite the information returned in either of these objects by any of the other functions. 8139 The ctime( ) function need not be reentrant. A function that is not required to be reentrant is not 8140 required to be thread-safe. 8141 TSF The ctime_r( ) function shall convert the calendar time pointed to by clock to local time in exactly 8142 the same form as ctime( ) and puts the string into the array pointed to by buf (which contains at 8143 least 26 bytes) and return buf. 8144 Unlike ctime( ), the thread-safe version ctime_r( ) is not required to set tzname. 8145 RETURN VALUE 8146 The ctime( ) function shall return the pointer returned by asctime( ) with that broken-down time 8147 as an argument. 8148 TSF Upon successful completion, ctime_r( ) shall return a pointer to the string pointed to by buf. 8149 When an error is encountered, a null pointer shall be returned. 8150 ERRORS 8151 No errors are defined. 8152 EXAMPLES 8153 None. 8154 APPLICATION USAGE 8155 Values for the broken-down time structure can be obtained by calling gmtime( ) or localtime( ). 8156 The ctime( ) function is included for compatibility with older implementations, and does not 8157 support localized date and time formats. Applications should use the strftime( ) function to 8158 achieve maximum portability. 8159 The ctime_r( ) function is thread-safe and shall return values in a user-supplied buffer instead of 8160 possibly using a static data area that may be overwritten by each call. 8161 RATIONALE 8162 None. 740 Technical Standard (2000) (Draft July 31, 2000) System Interfaces ctime( ) 8163 FUTURE DIRECTIONS 8164 None. 8165 SEE ALSO 8166 asctime( ), clock( ), difftime( ), gmtime( ), localtime( ), mktime( ), strftime( ), strptime( ), time( ), utime( ), | 8167 the Base Definitions volume of IEEE Std. 1003.1-200x, | 8168 CHANGE HISTORY 8169 First released in Issue 1. Derived from Issue 1 of the SVID. | 8170 Issue 4 8171 The APPLICATION USAGE section is expanded to describe the time-handling functions 8172 generally and to refer users to strftime( ), which is a locale-dependent time-handling function. 8173 The following change is incorporated for alignment with the ISO C standard: 8174 * The type of argument clock is changed from time_t* to const time_t*. 8175 Issue 5 8176 Normative text previously in the APPLICATION USAGE section is moved to the 8177 DESCRIPTION. 8178 The ctime_r( ) function is included for alignment with the POSIX Threads Extension. 8179 A note indicating that the ctime( ) function need not be reentrant is added to the DESCRIPTION. 8180 Issue 6 8181 Extensions beyond the ISO C standard are now marked. 8182 In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. 8183 The APPLICATION USAGE section is updated to include a note on the thread-safe function and 8184 its avoidance of possibly using a static data area. System Interfaces, Issue 6 741 daylight System Interfaces 8185 NAME 8186 daylight - daylight savings time flag 8187 SYNOPSIS 8188 XSI #include 8189 extern int daylight; 8190 8191 DESCRIPTION 8192 Refer to tzset( ). 742 Technical Standard (2000) (Draft July 31, 2000) System Interfaces dbm_clearerr( ) 8193 NAME 8194 dbm_clearerr, dbm_close, dbm_delete, dbm_error, dbm_fetch, dbm_firstkey, dbm_nextkey, 8195 dbm_open, dbm_store - database functions 8196 SYNOPSIS 8197 XSI #include 8198 int dbm_clearerr(DBM *db); 8199 void dbm_close(DBM *db); 8200 int dbm_delete(DBM *db, datum key); 8201 int dbm_error(DBM *db); 8202 datum dbm_fetch(DBM *db, datum key); 8203 datum dbm_firstkey(DBM *db); 8204 datum dbm_nextkey(DBM *db); 8205 DBM *dbm_open(const char *file, int open_flags, mode_t file_mode); 8206 int dbm_store(DBM *db, datum key, datum content, int store_mode); 8207 8208 DESCRIPTION 8209 These functions create, access, and modify a database. 8210 A datum consists of at least two members, dptr and dsize. The dptr member points to an object 8211 that is dsize bytes in length. Arbitrary binary data, as well as character strings, may be stored in 8212 the object pointed to by dptr. 8213 The database is stored in two files. One file is a directory containing a bit map of keys and has 8214 .dir as its suffix. The second file contains all data and has .pag as its suffix. 8215 The dbm_open( ) function shall open a database. The file argument to the function is the path 8216 name of the database. The function opens two files named file.dir and file.pag. The open_flags 8217 argument has the same meaning as the flags argument of open( ) except that a database opened 8218 for write-only access opens the files for read and write access and the behavior of the 8219 O_APPEND flag is unspecified. The file_mode argument has the same meaning as the third 8220 argument of open( ). 8221 The dbm_close( ) function shall close a database. The application shall ensure that argument db is 8222 a pointer to a dbm structure that has been returned from a call to dbm_open( ). 8223 The dbm_fetch( ) function shall read a record from a database. The argument db is a pointer to a 8224 database structure that has been returned from a call to dbm_open( ). The argument key is a 8225 datum that has been initialized by the application to the value of the key that matches the key of 8226 the record the program is fetching. 8227 The dbm_store( ) function shall write a record to a database. The argument db is a pointer to a 8228 database structure that has been returned from a call to dbm_open( ). The argument key is a 8229 datum that has been initialized by the application to the value of the key that identifies (for 8230 subsequent reading, writing, or deleting) the record the application is writing. The argument 8231 content is a datum that has been initialized by the application to the value of the record the 8232 program is writing. The argument store_mode controls whether dbm_store( ) replaces any pre- 8233 existing record that has the same key that is specified by the key argument. The application shall 8234 set store_mode to either DBM_INSERT or DBM_REPLACE. If the database contains a record that 8235 matches the key argument and store_mode is DBM_REPLACE, the existing record is replaced with 8236 the new record. If the database contains a record that matches the key argument and store_mode 8237 is DBM_INSERT, the existing record is left unchanged and the new record ignored. If the 8238 database does not contain a record that matches the key argument and store_mode is either 8239 DBM_INSERT or DBM_REPLACE, the new record is inserted in the database. System Interfaces, Issue 6 743 dbm_clearerr( ) System Interfaces 8240 The application shall ensure that the sum of the sizes of a key/content pair does not exceed the | 8241 internal block size. Moreover, the application shall ensure that all key/content pairs that hash | 8242 together fit on a single block. The dbm_store( ) function shall return an error in the event that a | 8243 disk block fills with inseparable data. 8244 The dbm_delete( ) function shall delete a record and its key from the database. The argument db is 8245 a pointer to a database structure that has been returned from a call to dbm_open( ). The argument 8246 key is a datum that has been initialized by the application to the value of the key that identifies 8247 the record the program is deleting. 8248 The dbm_firstkey( ) function shall return the first key in the database. The argument db is a 8249 pointer to a database structure that has been returned from a call to dbm_open( ). 8250 The dbm_nextkey( ) function shall return the next key in the database. The argument db is a 8251 pointer to a database structure that has been returned from a call to dbm_open( ). The application 8252 shall ensure that the dbm_firstkey( ) function is called before calling dbm_nextkey( ). Subsequent 8253 calls to dbm_nextkey( ) return the next key until all of the keys in the database have been 8254 returned. 8255 The dbm_error( ) function shall return the error condition of the database. The argument db is a 8256 pointer to a database structure that has been returned from a call to dbm_open( ). 8257 The dbm_clearerr( ) function shall clear the error condition of the database. The argument db is a 8258 pointer to a database structure that has been returned from a call to dbm_open( ). 8259 These database functions shall support an internal block size large enough to support | 8260 key/content pairs of at least 1 023 bytes. | 8261 The dptr pointers returned by these functions may point into static storage that may be changed 8262 by subsequent calls. 8263 These functions need not be reentrant. A function that is not required to be reentrant is not 8264 required to be thread-safe. 8265 RETURN VALUE 8266 The dbm_store( ) and dbm_delete( ) functions shall return 0 when they succeed and a negative 8267 value when they fail. 8268 The dbm_store( ) function shall return 1 if it is called with a flags value of DBM_INSERT and the 8269 function finds an existing record with the same key. 8270 The dbm_error( ) function shall return 0 if the error condition is not set and return a non-zero 8271 value if the error condition is set. 8272 The return value of dbm_clearerr( ) is unspecified. 8273 The dbm_firstkey( ) and dbm_nextkey( ) functions shall return a key datum. When the end of the 8274 database is reached, the dptr member of the key is a null pointer. If an error is detected, the dptr 8275 member of the key shall be a null pointer and the error condition of the database shall be set. 8276 The dbm_fetch( ) function shall return a content datum. If no record in the database matches the 8277 key or if an error condition has been detected in the database, the dptr member of the content 8278 shall be a null pointer. 8279 The dbm_open( ) function shall return a pointer to a database structure. If an error is detected 8280 during the operation, dbm_open( ) shall return a (DBM*)0. 744 Technical Standard (2000) (Draft July 31, 2000) System Interfaces dbm_clearerr( ) 8281 ERRORS 8282 No errors are defined. 8283 EXAMPLES 8284 None. 8285 APPLICATION USAGE 8286 The following code can be used to traverse the database: 8287 for(key = dbm_firstkey(db); key.dptr != NULL; key = dbm_nextkey(db)) 8288 The dbm_ functions provided in this library should not be confused in any way with those of a 8289 general-purpose database management system. These functions do not provide for multiple 8290 search keys per entry, they do not protect against multi-user access (in other words they do not 8291 lock records or files), and they do not provide the many other useful database functions that are 8292 found in more robust database management systems. Creating and updating databases by use of 8293 these functions is relatively slow because of data copies that occur upon hash collisions. These 8294 functions are useful for applications requiring fast lookup of relatively static information that is 8295 to be indexed by a single key. 8296 The dbm_delete( ) function need not physically reclaim file space, although it does make it 8297 available for reuse by the database. 8298 After calling dbm_store( ) or dbm_delete( ) during a pass through the keys by dbm_firstkey( ) and 8299 dbm_nextkey( ), the application should reset the database by calling dbm_firstkey( ) before again 8300 calling dbm_nextkey( ). The contents of these files are unspecified and may not be portable. 8301 RATIONALE 8302 None. 8303 FUTURE DIRECTIONS 8304 None. 8305 SEE ALSO 8306 open( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 8307 CHANGE HISTORY 8308 First released in Issue 4, Version 2. 8309 Issue 5 8310 Moved from X/OPEN UNIX extension to BASE. 8311 Normative text previously in the APPLICATION USAGE section is moved to the 8312 DESCRIPTION. 8313 A note indicating that these functions need not be reentrant is added to the DESCRIPTION. 8314 Issue 6 8315 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 745 difftime( ) System Interfaces 8316 NAME 8317 difftime - compute the difference between two calendar time values 8318 SYNOPSIS 8319 #include 8320 double difftime(time_t time1, time_t time0); 8321 DESCRIPTION 8322 CX The functionality described on this reference page is aligned with the ISO C standard. Any 8323 conflict between the requirements described here and the ISO C standard is unintentional. This 8324 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 8325 The difftime( ) function shall compute the difference between two calendar times (as returned by 8326 time( )): time1- time0. 8327 RETURN VALUE 8328 The difftime( ) function shall return the difference expressed in seconds as a type double. 8329 ERRORS 8330 No errors are defined. 8331 EXAMPLES 8332 None. 8333 APPLICATION USAGE 8334 None. 8335 RATIONALE 8336 None. 8337 FUTURE DIRECTIONS 8338 None. 8339 SEE ALSO 8340 asctime( ), clock( ), ctime( ), gmtime( ), localtime( ), mktime( ), strftime( ), strptime( ), time( ), utime( ), | 8341 the Base Definitions volume of IEEE Std. 1003.1-200x, | 8342 CHANGE HISTORY 8343 First released in Issue 4. Derived from the ISO C standard. | 746 Technical Standard (2000) (Draft July 31, 2000) System Interfaces dirname( ) 8344 NAME 8345 dirname - report the parent directory name of a file path name | 8346 SYNOPSIS 8347 XSI #include 8348 char *dirname(char *path); 8349 8350 DESCRIPTION 8351 The dirname( ) function shall take a pointer to a character string that contains a path name, and 8352 return a pointer to a string that is a path name of the parent directory of that file. Trailing '/' 8353 characters in the path are not counted as part of the path. 8354 If path does not contain a '/', then dirname( ) shall return a pointer to the string ".". If path is a 8355 null pointer or points to an empty string, dirname( ) shall return a pointer to the string ".". 8356 The dirname( ) function need not be reentrant. A function that is not required to be reentrant is 8357 not required to be thread-safe. 8358 RETURN VALUE 8359 The dirname( ) function shall return a pointer to a string that is the parent directory of path. If 8360 path is a null pointer or points to an empty string, a pointer to a string "." is returned. 8361 The dirname( ) function may modify the string pointed to by path, and may return a pointer to 8362 static storage that may then be overwritten by subsequent calls to dirname( ). 8363 ERRORS 8364 No errors are defined. 8365 EXAMPLES 8366 The following code fragment reads a path name, changes the current working directory to the 8367 parent directory, and opens the file. 8368 char path[MAXPATHLEN], *pathcopy; 8369 int fd; 8370 fgets(path, MAXPATHLEN, stdin); 8371 pathcopy = strdup(path); 8372 chdir(dirname(pathcopy)); 8373 fd = open(basename(path), O_RDONLY); 8374 Sample Input and Output Strings for dirname( ) 8375 In the following table, the input string is the value pointed to by path, and the output string is 8376 the return value of the dirname( ) function. ______________________________ 8377 _ Input String Output String _____________________________ 8378 "/usr/lib" "/usr" 8379 "/usr/" "/" 8380 "usr" "." 8381 "/" "/" 8382 "." "." 8383 _ ".." "." _____________________________ System Interfaces, Issue 6 747 dirname( ) System Interfaces 8384 Changing the Current Directory to the Parent Directory 8385 The following program fragment reads a path name, changes the current working directory to 8386 the parent directory, and opens the file. 8387 #include 8388 #include 8389 #include 8390 #include 8391 #include 8392 #include 8393 ... 8394 char path[PATH_MAX], *pathcopy; 8395 int fd; 8396 ... 8397 fgets(path, PATH_MAX, stdin); 8398 pathcopy = strdup(path); 8399 chdir(dirname(pathcopy)); 8400 fd = open(basename(path), O_RDONLY); 8401 APPLICATION USAGE 8402 The dirname( ) and basename( ) functions together yield a complete path name. The expression 8403 dirname(path) obtains the path name of the directory where basename(path) is found. 8404 Since the meaning of the leading "//" is implementation-defined, dirname("//foo) may return | 8405 either "//" or '/' (but nothing else). | 8406 RATIONALE 8407 None. 8408 FUTURE DIRECTIONS 8409 None. 8410 SEE ALSO 8411 basename( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 8412 CHANGE HISTORY 8413 First released in Issue 4, Version 2. 8414 Issue 5 8415 Moved from X/OPEN UNIX extension to BASE. 8416 Normative text previously in the APPLICATION USAGE section is moved to the 8417 DESCRIPTION. 8418 A note indicating that this function need not be reentrant is added to the DESCRIPTION. 748 Technical Standard (2000) (Draft July 31, 2000) System Interfaces div( ) 8419 NAME 8420 div - compute the quotient and remainder of an integer division 8421 SYNOPSIS 8422 #include 8423 div_t div(int numer, int denom); 8424 DESCRIPTION 8425 CX The functionality described on this reference page is aligned with the ISO C standard. Any 8426 conflict between the requirements described here and the ISO C standard is unintentional. This 8427 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 8428 The div( ) function shall compute the quotient and remainder of the division of the numerator 8429 numer by the denominator denom. If the division is inexact, the resulting quotient is the integer 8430 of lesser magnitude that is the nearest to the algebraic quotient. If the result cannot be 8431 represented, the behavior is undefined; otherwise, quot*denom+rem shall equal numer. 8432 RETURN VALUE 8433 The div( ) function shall return a structure of type div_t, comprising both the quotient and the 8434 remainder. The structure includes the following members, in any order: 8435 int quot; /* quotient */ 8436 int rem; /* remainder */ 8437 ERRORS 8438 No errors are defined. 8439 EXAMPLES 8440 None. 8441 APPLICATION USAGE 8442 None. 8443 RATIONALE 8444 None. 8445 FUTURE DIRECTIONS 8446 None. 8447 SEE ALSO 8448 ldiv( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 8449 CHANGE HISTORY 8450 First released in Issue 4. Derived from the ISO C standard. | System Interfaces, Issue 6 749 dlclose( ) System Interfaces 8451 NAME 8452 dlclose - close a dlopen( ) object 8453 SYNOPSIS 8454 XSI #include 8455 int dlclose(void *handle); | 8456 | 8457 DESCRIPTION 8458 The dlclose( ) function is used to inform the system that the object referenced by a handle returned 8459 from a previous dlopen( ) invocation is no longer needed by the application. 8460 The use of dlclose( ) reflects a statement of intent on the part of the process, but does not create 8461 any requirement upon the implementation, such as removal of the code or symbols referenced 8462 by handle. Once an object has been closed using dlclose( ) an application should assume that its 8463 symbols are no longer available to dlsym( ). All objects loaded automatically as a result of 8464 invoking dlopen( ) on the referenced object are also closed if this is the last reference to it. 8465 Although a dlclose( ) operation is not required to remove structures from an address space, 8466 neither is an implementation prohibited from doing so. The only restriction on such a removal is 8467 that no object shall be removed to which references have been relocated, until or unless all such 8468 references are removed. For instance, an object that had been loaded with a dlopen( ) operation 8469 specifying the RTLD_GLOBAL flag might provide a target for dynamic relocations performed in 8470 the processing of other objects-in such environments, an application may assume that no 8471 relocation, once made, shall be undone or remade unless the object requiring the relocation has 8472 itself been removed. 8473 RETURN VALUE 8474 If the referenced object was successfully closed, dlclose( ) shall return 0. If the object could not be 8475 closed, or if handle does not refer to an open object, dlclose( ) shall return a non-zero value. More 8476 detailed diagnostic information shall be available through dlerror( ). 8477 ERRORS 8478 No errors are defined. 8479 EXAMPLES 8480 The following example illustrates use of dlopen( ) and dlclose( ): 8481 ... 8482 /* Open a dynamic library and then close it ... */ 8483 #include 8484 void *mylib; 8485 int eret; 8486 mylib = dlopen("mylib.so.1", RTLD_LAZY); 8487 ... 8488 eret = dlclose(mylib); 8489 ... 8490 APPLICATION USAGE 8491 A portable application should employ a handle returned from a dlopen( ) invocation only within a 8492 given scope bracketed by the dlopen( ) and dlclose( ) operations. Implementations are free to use 8493 reference counting or other techniques such that multiple calls to dlopen( ) referencing the same 8494 object may return the same object for handle. Implementations are also free to reuse a handle. 8495 For these reasons, the value of a handle must be treated as an opaque object by the application, 8496 used only in calls to dlsym( ) and dlclose( ). 750 Technical Standard (2000) (Draft July 31, 2000) System Interfaces dlclose( ) 8497 RATIONALE 8498 None. 8499 FUTURE DIRECTIONS 8500 None. 8501 SEE ALSO 8502 dlerror( ), dlopen( ), dlsym( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 8503 CHANGE HISTORY 8504 First released in Issue 5. 8505 Issue 6 8506 The DESCRIPTION is updated to say that the referenced object is closed ``if this is the last 8507 reference to it''. System Interfaces, Issue 6 751 dlerror( ) System Interfaces 8508 NAME 8509 dlerror - get diagnostic information 8510 SYNOPSIS 8511 XSI #include 8512 char *dlerror(void); 8513 8514 DESCRIPTION 8515 The dlerror( ) function shall return a null-terminated character string (with no trailing ) 8516 that describes the last error that occurred during dynamic linking processing. If no dynamic 8517 linking errors have occurred since the last invocation of dlerror( ), dlerror( ) shall return NULL. 8518 Thus, invoking dlerror( ) a second time, immediately following a prior invocation, shall result in 8519 NULL being returned. 8520 The dlerror( ) function need not be reentrant. A function that is not required to be reentrant is not 8521 required to be thread-safe. 8522 RETURN VALUE 8523 If successful, dlerror( ) shall return a null-terminated character string; otherwise, NULL shall be 8524 returned. 8525 ERRORS 8526 No errors are defined. 8527 EXAMPLES 8528 The following example prints out the last dynamic linking error: 8529 ... 8530 #include 8531 char *errstr; 8532 errstr = dlerror(); 8533 if (errstr != NULL) 8534 printf ("A dynamic linking error occurred: (%s)\n", errstr); 8535 ... 8536 APPLICATION USAGE 8537 The messages returned by dlerror( ) may reside in a static buffer that is overwritten on each call 8538 to dlerror( ). Application code should not write to this buffer. Programs wishing to preserve an 8539 error message should make their own copies of that message. Depending on the application 8540 environment with respect to asynchronous execution events, such as signals or other 8541 asynchronous computation sharing the address space, portable applications should use a critical 8542 section to retrieve the error pointer and buffer. 8543 RATIONALE 8544 None. 8545 FUTURE DIRECTIONS 8546 None. 8547 SEE ALSO 8548 dlclose( ), dlopen( ), dlsym( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 752 Technical Standard (2000) (Draft July 31, 2000) System Interfaces dlerror( ) 8549 CHANGE HISTORY 8550 First released in Issue 5. 8551 Issue 6 8552 In the DESCRIPTION the note about reentrancy and thread-safety is added. System Interfaces, Issue 6 753 dlopen( ) System Interfaces 8553 NAME 8554 dlopen - gain access to an executable object file 8555 SYNOPSIS 8556 XSI #include 8557 void *dlopen(const char *file, int mode); 8558 8559 DESCRIPTION 8560 The dlopen( ) function shall make an executable object file specified by file available to the calling 8561 program. The class of files eligible for this operation and the manner of their construction are 8562 specified by the implementation, though typically such files are executable objects such as 8563 shared libraries, relocatable files, or programs. Note that some implementations permit the 8564 construction of dependencies between such objects that are embedded within files. In such 8565 cases, a dlopen( ) operation shall load such dependencies in addition to the object referenced by 8566 file. Implementations may also impose specific constraints on the construction of programs that 8567 can employ dlopen( ) and its related services. 8568 A successful dlopen( ) shall return a handle which the caller may use on subsequent calls to 8569 dlsym( ) and dlclose( ). The value of this handle should not be interpreted in any way by the caller. 8570 file is used to construct a path name to the object file. If file contains a slash character, the file 8571 argument is used as the path name for the file. Otherwise, file is used in an implementation- | 8572 defined manner to yield a path name. | 8573 If the value of file is 0, dlopen( ) shall provide a handle on a global symbol object. This object 8574 provides access to the symbols from an ordered set of objects consisting of the original program 8575 image file, together with any objects loaded at program start-up as specified by that process 8576 image file (for example, shared libraries), and the set of objects loaded using a dlopen( ) operation 8577 together with the RTLD_GLOBAL flag. As the latter set of objects can change during execution, 8578 the set identified by handle can also change dynamically. 8579 Only a single copy of an object file is brought into the address space, even if dlopen( ) is invoked 8580 multiple times in reference to the file, and even if different path names are used to reference the 8581 file. 8582 The mode parameter describes how dlopen( ) shall operate upon file with respect to the processing 8583 of relocations and the scope of visibility of the symbols provided within file. When an object is 8584 brought into the address space of a process, it may contain references to symbols whose 8585 addresses are not known until the object is loaded. These references shall be relocated before the 8586 symbols can be accessed. The mode parameter governs when these relocations take place and 8587 may have the following values: 8588 RTLD_LAZY Relocations shall be performed at an implementation-defined time, | 8589 ranging from the time of the dlopen( ) call until the first reference to a 8590 given symbol occurs. Specifying RTLD_LAZY should improve 8591 performance on implementations supporting dynamic symbol binding as 8592 a process may not reference all of the functions in any given object. And, 8593 for systems supporting dynamic symbol resolution for normal process 8594 execution, this behavior mimics the normal handling of process 8595 execution. 8596 RTLD_NOW All necessary relocations shall be performed when the object is first 8597 loaded. This may waste some processing if relocations are performed for 8598 functions that are never referenced. This behavior may be useful for 8599 applications that need to know as soon as an object is loaded that all | 754 Technical Standard (2000) (Draft July 31, 2000) System Interfaces dlopen( ) 8600 symbols referenced during execution are available. | 8601 Any object loaded by dlopen( ) that requires relocations against global symbols can reference the 8602 symbols in the original process image file, any objects loaded at program start-up, from the 8603 object itself as well as any other object included in the same dlopen( ) invocation, and any objects 8604 that were loaded in any dlopen( ) invocation and which specified the RTLD_GLOBAL flag. To 8605 determine the scope of visibility for the symbols loaded with a dlopen( ) invocation, the mode 8606 parameter should be a bitwise-inclusive OR with one of the following values: 8607 RTLD_GLOBAL The object's symbols shall be made available for the relocation processing 8608 of any other object. In addition, symbol lookup using dlopen(0, mode) and 8609 an associated dlsym( ) allows objects loaded with this mode to be searched. 8610 RTLD_LOCAL The object's symbols shall not be made available for the relocation 8611 processing of any other object. 8612 If neither RTLD_GLOBAL nor RTLD_LOCAL are specified, then an implementation-defined | 8613 default behavior shall be applied. | 8614 If a file is specified in multiple dlopen( ) invocations, mode is interpreted at each invocation. Note, 8615 however, that once RTLD_NOW has been specified all relocations shall have been completed 8616 rendering further RTLD_NOW operations redundant and any further RTLD_LAZY operations 8617 irrelevant. Similarly, note that once RTLD_GLOBAL has been specified the object shall maintain 8618 the RTLD_GLOBAL status regardless of any previous or future specification of RTLD_LOCAL, 8619 as long as the object remains in the address space (see dlclose( )). 8620 Symbols introduced into a program through calls to dlopen( ) may be used in relocation 8621 activities. Symbols so introduced may duplicate symbols already defined by the program or 8622 previous dlopen( ) operations. To resolve the ambiguities such a situation might present, the 8623 resolution of a symbol reference to symbol definition is based on a symbol resolution order. Two 8624 such resolution orders are defined: load or dependency ordering. Load order establishes an 8625 ordering among symbol definitions, such that the definition first loaded (including definitions 8626 from the image file and any dependent objects loaded with it) has priority over objects added 8627 later (via dlopen( )). Load ordering is used in relocation processing. Dependency ordering uses a 8628 breadth-first order starting with a given object, then all of its dependencies, then any dependents 8629 of those, iterating until all dependencies are satisfied. With the exception of the global symbol 8630 object obtained via a dlopen( ) operation on a file of 0, dependency ordering is used by the 8631 dlsym( ) function. Load ordering is used in dlsym( ) operations upon the global symbol object. 8632 When an object is first made accessible via dlopen( ) it and its dependent objects are added in 8633 dependency order. Once all the objects are added, relocations are performed using load order. 8634 Note that if an object or its dependencies had been previously loaded, the load and dependency 8635 orders may yield different resolutions. 8636 The symbols introduced by dlopen( ) operations, and available through dlsym( ) are at a 8637 minimum those which are exported as symbols of global scope by the object. Typically such 8638 symbols shall be those that were specified in (for example) C source code as having extern 8639 linkage. The precise manner in which an implementation constructs the set of exported symbols 8640 for a dlopen( ) object is specified by that implementation. 8641 RETURN VALUE 8642 If file cannot be found, cannot be opened for reading, is not of an appropriate object format for 8643 processing by dlopen( ), or if an error occurs during the process of loading file or relocating its 8644 symbolic references, dlopen( ) shall return NULL. More detailed diagnostic information shall be 8645 available through dlerror( ). System Interfaces, Issue 6 755 dlopen( ) System Interfaces 8646 ERRORS 8647 No errors are defined. 8648 EXAMPLES 8649 None. 8650 APPLICATION USAGE 8651 None. 8652 RATIONALE 8653 None. 8654 FUTURE DIRECTIONS 8655 None. 8656 SEE ALSO 8657 dlclose( ), dlerror( ), dlsym( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 8658 CHANGE HISTORY 8659 First released in Issue 5. 756 Technical Standard (2000) (Draft July 31, 2000) System Interfaces dlsym( ) 8660 NAME 8661 dlsym - obtain the address of a symbol from a dlopen( ) object 8662 SYNOPSIS 8663 XSI #include 8664 void *dlsym(void *restrict handle, const char *restrict name); | 8665 | 8666 DESCRIPTION 8667 The dlsym( ) function allows a process to obtain the address of a symbol defined within an object 8668 made accessible through a dlopen( ) call. handle is the value returned from a call to dlopen( ) (and 8669 which has not since been released via a call to dlclose( )), and name is the symbol's name as a 8670 character string. 8671 The dlsym( ) function shall search for the named symbol in all objects loaded automatically as a 8672 result of loading the object referenced by handle (see dlopen( )). Load ordering is used in dlsym( ) 8673 operations upon the global symbol object. The symbol resolution algorithm used shall be 8674 dependency order as described in dlopen( ). 8675 The RTLD_NEXT flag is reserved for future use. 8676 RETURN VALUE 8677 If handle does not refer to a valid object opened by dlopen( ), or if the named symbol cannot be 8678 found within any of the objects associated with handle, dlsym( ) shall return NULL. More 8679 detailed diagnostic information shall be available through dlerror( ). 8680 ERRORS 8681 No errors are defined. 8682 EXAMPLES 8683 The following example shows how dlopen( ) and dlsym( ) can be used to access either function or 8684 data objects. For simplicity, error checking has been omitted. 8685 void *handle; 8686 int *iptr, (*fptr)(int); 8687 /* open the needed object */ 8688 handle = dlopen("/usr/home/me/libfoo.so.1", RTLD_LAZY); 8689 /* find the address of function and data objects */ 8690 fptr = (int (*)(int))dlsym(handle, "my_function"); 8691 iptr = (int *)dlsym(handle, "my_object"); 8692 /* invoke function, passing value of integer as a parameter */ 8693 (*fptr)(*iptr); 8694 APPLICATION USAGE 8695 Special purpose values for handle are reserved for future use. These values and their meanings 8696 are: 8697 RTLD_NEXT Specifies the next object after this one that defines name. This one refers to the 8698 object containing the invocation of dlsym( ). The next object is the one found 8699 upon the application of a load order symbol resolution algorithm (see 8700 dlopen( )). The next object is either one of global scope (because it was 8701 introduced as part of the original process image or because it was added with 8702 a dlopen( ) operation including the RTLD_GLOBAL flag), or is an object that 8703 was included in the same dlopen( ) operation that loaded this one. System Interfaces, Issue 6 757 dlsym( ) System Interfaces 8704 The RTLD_NEXT flag is useful to navigate an intentionally created hierarchy 8705 of multiply-defined symbols created through interposition. For example, if a 8706 program wished to create an implementation of malloc( ) that embedded some 8707 statistics gathering about memory allocations, such an implementation could 8708 use the real malloc( ) definition to perform the memory allocation-and itself 8709 only embed the necessary logic to implement the statistics gathering function. 8710 RATIONALE 8711 None. 8712 FUTURE DIRECTIONS 8713 None. 8714 SEE ALSO 8715 dlclose( ), dlerror( ), dlopen( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 8716 CHANGE HISTORY 8717 First released in Issue 5. | 8718 Issue 6 | 8719 The restrict keyword is added to the dlsym( ) prototype for alignment with the | 8720 ISO/IEC 9899: 1999 standard. | 758 Technical Standard (2000) (Draft July 31, 2000) System Interfaces drand48( ) 8721 NAME 8722 drand48, erand48, jrand48, lcong48, lrand48, mrand48, nrand48, seed48, srand48 - generate 8723 uniformly distributed pseudo-random numbers 8724 SYNOPSIS 8725 XSI #include 8726 double drand48(void); 8727 double erand48(unsigned short xsubi[3]); | 8728 long jrand48(unsigned short xsubi[3]); | 8729 void lcong48(unsigned short param[7]); | 8730 long lrand48(void); | 8731 long mrand48(void); | 8732 long nrand48(unsigned short xsubi[3]); | 8733 unsigned short *seed48(unsigned short seed16v[3]); | 8734 void srand48(long seedval); | 8735 | 8736 DESCRIPTION 8737 This family of functions generates pseudo-random numbers using a linear congruential 8738 algorithm and 48-bit integer arithmetic. 8739 The drand48( ) and erand48( ) functions shall return non-negative, double-precision, floating- 8740 point values, uniformly distributed over the interval [0.0,1.0). 8741 The lrand48( ) and nrand48( ) functions shall return non-negative, long integers, uniformly 8742 distributed over the interval [0,231). 8743 The mrand48( ) and jrand48( ) functions shall return signed long integers uniformly distributed 8744 over the interval [-231,231). 8745 The srand48( ), seed48( ), and lcong48( ) are initialization entry points, one of which should be 8746 invoked before either drand48( ), lrand48( ), or mrand48( ) is called. (Although it is not 8747 recommended practice, constant default initializer values shall be supplied automatically if 8748 drand48( ), lrand48( ), or mrand48( ) is called without a prior call to an initialization entry point.) 8749 The erand48( ), nrand48( ), and jrand48( ) functions do not require an initialization entry point to 8750 be called first. 8751 All the routines work by generating a sequence of 48-bit integer values, Xi, according to the 8752 linear congruential formula: 8753 Xn+1 = (aXn + c)mod m n 0 8754 The parameter m = 248; hence 48-bit integer arithmetic is performed. Unless lcong48( ) is invoked, 8755 the multiplier value a and the addend value c are given by: 8756 a = 5DEECE66D 16 = 273673163155 8 8757 c = B 16 = 13 8 8758 The value returned by any of the drand48( ), erand48( ), jrand48( ), lrand48( ), mrand48( ), or 8759 nrand48( ) functions is computed by first generating the next 48-bit Xi in the sequence. Then the 8760 appropriate number of bits, according to the type of data item to be returned, are copied from 8761 the high-order (leftmost) bits of Xi and transformed into the returned value. 8762 The drand48( ), lrand48( ), and mrand48( ) functions store the last 48-bit Xi generated in an 8763 internal buffer; that is why the application shall ensure that these are initialized prior to being 8764 invoked. The erand48( ), nrand48( ), and jrand48( ) functions require the calling program to 8765 provide storage for the successive Xi values in the array specified as an argument when the System Interfaces, Issue 6 759 drand48( ) System Interfaces 8766 functions are invoked. That is why these routines do not have to be initialized; the calling 8767 program merely has to place the desired initial value of Xi into the array and pass it as an 8768 argument. By using different arguments, erand48( ), nrand48( ), and jrand48( ) allow separate 8769 modules of a large program to generate several independent streams of pseudo-random numbers; 8770 that is, the sequence of numbers in each stream shall not depend upon how many times the 8771 routines are called to generate numbers for the other streams. 8772 The initializer function srand48( ) sets the high-order 32 bits of Xi to the low-order 32 bits 8773 contained in its argument. The low-order 16 bits of Xi are set to the arbitrary value 330E16. 8774 The initializer function seed48( ) sets the value of Xi to the 48-bit value specified in the argument 8775 array. The low-order 16 bits of Xi are set to the low-order 16 bits of seed16v[0]. The mid-order 16 8776 bits of Xi are set to the low-order 16 bits of seed16v[1]. The high-order 16 bits of Xi are set to the 8777 low-order 16 bits of seed16v[2]. In addition, the previous value of Xi is copied into a 48-bit 8778 internal buffer, used only by seed48( ), and a pointer to this buffer is the value returned by 8779 seed48( ). This returned pointer, which can just be ignored if not needed, is useful if a program is 8780 to be restarted from a given point at some future time-use the pointer to get at and store the 8781 last Xi value, and then use this value to re-initialize via seed48( ) when the program is restarted. 8782 The initializer function lcong48( ) allows the user to specify the initial Xi, the multiplier value a, 8783 and the addend value c. Argument array elements param[0-2] specify Xi, param[3-5] specify the 8784 multiplier a, and param[6] specifies the 16-bit addend c. After lcong48( ) is called, a subsequent 8785 call to either srand48( ) or seed48( ) shall restore the standard multiplier and addend values, a and 8786 c, specified above. 8787 The drand48( ), lrand48( ), and mrand48( ) functions need not be reentrant. A function that is not 8788 required to be reentrant is not required to be thread-safe. 8789 RETURN VALUE 8790 As described in the DESCRIPTION above. 8791 ERRORS 8792 No errors are defined. 8793 EXAMPLES 8794 None. 8795 APPLICATION USAGE 8796 None. 8797 RATIONALE 8798 None. 8799 FUTURE DIRECTIONS 8800 None. 8801 SEE ALSO 8802 rand( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 8803 CHANGE HISTORY 8804 First released in Issue 1. Derived from Issue 1 of the SVID. | 8805 Issue 4 8806 The type long is replaced by long and the type unsigned short is replaced by unsigned short in | 8807 the SYNOPSIS section. 8808 In the DESCRIPTION, the description of srand48( ) is amended to fix a limitation in Issue 3, 8809 which indicates that the high-order 32 bits of Xi are set to the {LONG_BIT} bits in the argument. 8810 Though unintentional, the implication of this statement is that {LONG_BIT} would be 32 on all 760 Technical Standard (2000) (Draft July 31, 2000) System Interfaces drand48( ) 8811 systems compliant with Issue 3, when in fact Issue 3 imposes no such restriction. 8812 The header is added to the SYNOPSIS section. 8813 The argument list for the lrand48( ) and mrand48( ) functions now contains void. 8814 Issue 5 8815 A note indicating that these functions need not be reentrant is added to the DESCRIPTION. 8816 Issue 6 8817 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 761 dup( ) System Interfaces 8818 NAME 8819 dup, dup2 - duplicate an open file descriptor 8820 SYNOPSIS 8821 #include 8822 int dup(int fildes); 8823 int dup2(int fildes, int fildes2); 8824 DESCRIPTION 8825 The dup( ) and dup2( ) functions provide an alternative interface to the service provided by 8826 fcntl( ) using the F_DUPFD command. The call: 8827 fid = dup(fildes); 8828 is equivalent to: 8829 fid = fcntl(fildes, F_DUPFD, 0); 8830 The call: 8831 fid = dup2(fildes, fildes2); 8832 is equivalent to: 8833 close(fildes2); 8834 fid = fcntl(fildes, F_DUPFD, fildes2); 8835 except for the following: 8836 * If fildes2 is less than 0 or greater than or equal to {OPEN_MAX}, dup2( ) shall return -1 with 8837 errno set to [EBADF]. | 8838 * If fildes is a valid file descriptor and is equal to fildes2, dup2( ) shall return fildes2 without 8839 closing it. 8840 * If fildes is not a valid file descriptor, dup2( ) shall return -1 and shall not close fildes2. 8841 * The value returned shall be equal to the value of fildes2 upon successful completion, or -1 8842 upon failure. 8843 RETURN VALUE 8844 Upon successful completion a non-negative integer, namely the file descriptor, shall be returned; 8845 otherwise, -1 shall be returned and errno set to indicate the error. 8846 ERRORS 8847 The dup( ) function shall fail if: 8848 [EBADF] The fildes argument is not a valid open file descriptor. | 8849 [EMFILE] The number of file descriptors in use by this process would exceed | 8850 {OPEN_MAX}. 8851 The dup2( ) function shall fail if: 8852 [EBADF] The fildes argument is not a valid open file descriptor or the argument fildes2 is | 8853 negative or greater than or equal to {OPEN_MAX}. 8854 [EINTR] The dup2( ) function was interrupted by a signal. | 762 Technical Standard (2000) (Draft July 31, 2000) System Interfaces dup( ) 8855 EXAMPLES 8856 Redirecting Standard Output to a File 8857 The following example closes standard output for the current processes, re-assigns standard 8858 output to go to the file referenced by pfd, and closes the original file descriptor to clean up. 8859 #include 8860 ... 8861 int pfd; 8862 ... 8863 close(1); 8864 dup(pfd); 8865 close(pfd); 8866 ... 8867 Redirecting Error Messages 8868 The following example redirects messages from stderr to stdout. 8869 #include 8870 ... 8871 dup2(1, 2); 8872 ... 8873 APPLICATION USAGE 8874 None. 8875 RATIONALE 8876 The dup( ) and dup2( ) functions are redundant. Their services are also provided by the fcntl( ) 8877 function. They have been included in this volume of IEEE Std. 1003.1-200x primarily for 8878 historical reasons, since many existing applications use them. 8879 While the brief code segment shown is very similar in behavior to dup2( ), a conforming 8880 implementation based on other functions defined in this volume of IEEE Std. 1003.1-200x is 8881 significantly more complex. Least obvious is the possible effect of a signal-catching function that 8882 could be invoked between steps and allocate or deallocate file descriptors. This could be avoided 8883 by blocking signals. 8884 The dup2( ) function is not marked obsolescent because it presents a type-safe version of 8885 functionality provided in a type-unsafe version by fcntl( ). It is used in the POSIX Ada binding. 8886 The dup2( ) function is not intended for use in critical regions as a synchronization mechanism. 8887 In the description of [EBADF], the case of fildes being out of range is covered by the given case of | 8888 fildes not being valid. The descriptions for fildes and fildes2 are different because the only kind of 8889 invalidity that is relevant for fildes2 is whether it is out of range; that is, it does not matter 8890 whether fildes2 refers to an open file when the dup2( ) call is made. 8891 FUTURE DIRECTIONS 8892 None. 8893 SEE ALSO 8894 close( ), fcntl( ), open( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | System Interfaces, Issue 6 763 dup( ) System Interfaces 8895 CHANGE HISTORY 8896 First released in Issue 1. Derived from Issue 1 of the SVID. | 8897 Issue 4 8898 The header is added to the SYNOPSIS section. 8899 [EINTR] is no longer required for dup( ) because fcntl( ) does not return [EINTR] for F_DUPFD. 8900 The following changes are incorporated for alignment with the ISO POSIX-1 standard: 8901 * In the DESCRIPTION, the fourth bullet item describing differences between dup( ) and 8902 dup2( ) is added. 8903 * In the ERRORS section, error values returned by dup( ) and dup2( ) are now described 8904 separately. 8905 Issue 6 8906 The RATIONALE section is added. 764 Technical Standard (2000) (Draft July 31, 2000) System Interfaces ecvt( ) 8907 NAME 8908 ecvt, fcvt, gcvt - convert a floating-point number to a string (LEGACY) 8909 SYNOPSIS 8910 XSI #include 8911 char *ecvt(double value, int ndigit, int *restrict decpt, | 8912 int *restrict sign); | 8913 char *fcvt(double value, int ndigit, int *restrict decpt, | 8914 int *restrict sign); | 8915 char *gcvt(double value, int ndigit, char *buf); | 8916 8917 DESCRIPTION 8918 The ecvt( ), fcvt( ), and gcvt( ) functions shall convert floating-point numbers to null-terminated 8919 strings. 8920 The ecvt( ) function shall convert value to a null-terminated string of ndigit digits (where ndigit is 8921 reduced to an unspecified limit determined by the precision of a double) and return a pointer to 8922 the string. The high-order digit is non-zero, unless the value is 0. The low-order digit is rounded. 8923 The position of the radix character relative to the beginning of the string is stored in the integer 8924 pointed to by decpt (negative means to the left of the returned digits). If value is zero, it is 8925 unspecified whether the integer pointed to by decpt would be 0 or 1. The radix character is not 8926 included in the returned string. If the sign of the result is negative, the integer pointed to by sign 8927 is non-zero; otherwise, it is 0. 8928 If the converted value is out of range or is not representable, the contents of the returned string 8929 are unspecified. 8930 The fcvt( ) function is identical to ecvt( ) except that ndigit specifies the number of digits desired 8931 after the radix character. The total number of digits in the result string is restricted to an 8932 unspecified limit as determined by the precision of a double. 8933 The gcvt( ) function shall convert value to a null-terminated string (similar to that of the %g 8934 format of printf( )) in the array pointed to by buf and return buf. It produces ndigit significant 8935 digits (limited to an unspecified value determined by the precision of a double) in %f if possible, 8936 or %e (scientific notation) otherwise. A minus sign is included in the returned string if value is 8937 less than 0. A radix character is included in the returned string if value is not a whole number. 8938 Trailing zeros are suppressed where value is not a whole number. The radix character is 8939 determined by the current locale. If setlocale( ) has not been called successfully, the default locale, 8940 POSIX, is used. The default locale specifies a period ('.') as the radix character. The 8941 LC_NUMERIC category determines the value of the radix character within the current locale. 8942 These functions need not be reentrant. A function that is not required to be reentrant is not 8943 required to be thread-safe. 8944 RETURN VALUE 8945 The ecvt( ) and fcvt( ) functions shall return a pointer to a null-terminated string of digits. 8946 The gcvt( ) function shall return buf. 8947 The return values from ecvt( ) and fcvt( ) may point to static data which may be overwritten by 8948 subsequent calls to these functions. 8949 ERRORS 8950 No errors are defined. System Interfaces, Issue 6 765 ecvt( ) System Interfaces 8951 EXAMPLES 8952 None. 8953 APPLICATION USAGE 8954 sprintf( ) is preferred over this function. 8955 RATIONALE 8956 None. 8957 FUTURE DIRECTIONS 8958 These functions may be withdrawn in a future version. 8959 SEE ALSO 8960 printf( ), setlocale( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 8961 CHANGE HISTORY 8962 First released in Issue 4, Version 2. 8963 Issue 5 8964 Moved from X/OPEN UNIX extension to BASE. 8965 Normative text previously in the APPLICATION USAGE section is moved to the 8966 DESCRIPTION. 8967 A note indicating that these functions need not be reentrant is added to the DESCRIPTION. 8968 Issue 6 8969 In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. 8970 This function is marked LEGACY. | 8971 The restrict keyword is added to the ecvt( ) and fcvt( ) prototypes for alignment with the | 8972 ISO/IEC 9899: 1999 standard. | 766 Technical Standard (2000) (Draft July 31, 2000) System Interfaces encrypt( ) 8973 NAME 8974 encrypt - encoding function (CRYPT) 8975 SYNOPSIS 8976 XSI #include 8977 void encrypt(char block[64], int edflag); 8978 8979 DESCRIPTION 8980 The encrypt( ) function provides (rather primitive) access to an implementation-defined | 8981 encoding algorithm. The key generated by setkey( ) is used to encrypt the string block with | 8982 encrypt( ). 8983 The block argument to encrypt( ) is an array of length 64 bytes containing only the bytes with 8984 numerical value of 0 and 1. The array is modified in place to a similar array using the key set by 8985 setkey( ). If edflag is 0, the argument is encoded. If edflag is 1, the argument may be decoded (see 8986 the APPLICATION USAGE section); if the argument is not decoded, errno shall be set to 8987 [ENOSYS]. | 8988 The encrypt( ) function shall not change the setting of errno if successful. An application wishing 8989 to check for error situations should set errno to 0 before calling encrypt( ). If errno is non-zero on 8990 return, an error has occurred. 8991 The encrypt( ) function need not be reentrant. A function that is not required to be reentrant is 8992 not required to be thread-safe. 8993 RETURN VALUE 8994 The encrypt( ) function shall return no value. 8995 ERRORS 8996 The encrypt( ) function shall fail if: 8997 [ENOSYS] The functionality is not supported on this implementation. | 8998 EXAMPLES 8999 None. 9000 APPLICATION USAGE 9001 In some environments, decoding might not be implemented. This is related to U.S. Government 9002 restrictions on encryption and decryption routines: the DES decryption algorithm cannot be 9003 exported outside the U.S. Historical practice has been to ship a different version of the 9004 encryption library without the decryption feature in the routines supplied. Thus the exported 9005 version of encrypt( ) does encoding but not decoding. 9006 RATIONALE 9007 None. 9008 FUTURE DIRECTIONS 9009 None. 9010 SEE ALSO 9011 crypt( ), setkey( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 9012 CHANGE HISTORY 9013 First released in Issue 1. Derived from Issue 1 of the SVID. | System Interfaces, Issue 6 767 encrypt( ) System Interfaces 9014 Issue 4 9015 The header is added to the SYNOPSIS section. 9016 The DESCRIPTION is amended: 9017 * To specify the encoding algorithm as implementation-defined | 9018 * To change entry to function 9019 * To make decoding optional 9020 The APPLICATION USAGE section is expanded to explain the restrictions on the availability of 9021 the DES decryption algorithm. 9022 Issue 5 9023 A note indicating that this function need not be reentrant is added to the DESCRIPTION. 9024 Issue 6 9025 In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. 768 Technical Standard (2000) (Draft July 31, 2000) System Interfaces endgrent( ) 9026 NAME 9027 endgrent, getgrent, setgrent - group database entry functions 9028 SYNOPSIS 9029 XSI #include 9030 void endgrent(void); 9031 struct group *getgrent(void); 9032 void setgrent(void); 9033 9034 DESCRIPTION 9035 The endgrent( ) function may be called to close the group database when processing is complete. | 9036 An implementation that provides extended security controls may impose further | 9037 implementation-defined restrictions on accessing the group database. In particular, the system | 9038 may deny the existence of some or all of the group database entries associated with groups other | 9039 than those groups associated with the caller and may omit users other than the caller from the | 9040 list of members of groups in database entries that are returned. | 9041 The getgrent( ) function shall return a pointer to a structure containing the broken-out fields of an | 9042 entry in the group database. When first called, getgrent( ) shall return a pointer to a group 9043 structure containing the first entry in the group database. Thereafter, it shall return a pointer to a 9044 group structure containing the next group structure in the group database, so successive calls 9045 may be used to search the entire database. 9046 The setgrent( ) function effectively rewinds the group database to allow repeated searches. 9047 These functions need not be reentrant. A function that is not required to be reentrant is not | 9048 required to be thread-safe. 9049 RETURN VALUE 9050 When first called, getgrent( ) shall return a pointer to the first group structure in the group 9051 database. Upon subsequent calls it shall return the next group structure in the group database. 9052 The getgrent( ) function shall return a null pointer on end-of-file or an error and errno may be set 9053 to indicate the error. 9054 The return value may point to a static area which is overwritten by a subsequent call to 9055 getgrgid( ), getgrnam( ), or getgrent( ). 9056 ERRORS 9057 The getgrent( ) function may fail if: 9058 [EINTR] A signal was caught during the operation. | 9059 [EIO] An I/O error has occurred. | 9060 [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. | 9061 [ENFILE] The maximum allowable number of files is currently open in the system. | System Interfaces, Issue 6 769 endgrent( ) System Interfaces 9062 EXAMPLES 9063 None. 9064 APPLICATION USAGE 9065 These functions are provided due to their historical usage. Applications should avoid 9066 dependencies on fields in the group database, whether the database is a single file, or where in 9067 the file system name space the database resides. Applications should use getgrnam( ) and 9068 getgrgid( ) whenever possible because it avoids these dependencies. 9069 RATIONALE 9070 None. 9071 FUTURE DIRECTIONS 9072 None. 9073 SEE ALSO 9074 getgrgid( ), getgrnam( ), getlogin( ), getpwent( ), the Base Definitions volume of | 9075 IEEE Std. 1003.1-200x, | 9076 CHANGE HISTORY 9077 First released in Issue 4, Version 2. 9078 Issue 5 9079 Moved from X/OPEN UNIX extension to BASE. 9080 Normative text previously in the APPLICATION USAGE section is moved to the RETURN 9081 VALUE section. 9082 A note indicating that these functions need not be reentrant is added to the DESCRIPTION. 9083 Issue 6 9084 In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. 770 Technical Standard (2000) (Draft July 31, 2000) System Interfaces endhostent( ) 9085 NAME 9086 endhostent, freehostent, gethostent, sethostent - network host database functions 9087 SYNOPSIS 9088 #include 9089 void endhostent(void); 9090 void freehostent(struct hostent *ptr); 9091 struct hostent *gethostent(void); 9092 void sethostent(int stayopen); 9093 DESCRIPTION 9094 These functions enable applications to retrieve information about hosts. This information is 9095 considered to be stored in a database that can be accessed sequentially or randomly. 9096 Implementation of this database is unspecified. 9097 Note: In many cases it is implemented by the Domain Name System, as documented in 9098 RFC 1034, RFC 1035, and RFC 1886. 9099 Entries are returned in hostent structures. Refer to gethostbyaddr( ) for a definition of the hostent 9100 structure. 9101 The endhostent( ) function shall close the connection to the database, releasing any open file 9102 descriptor. 9103 The freehostent( ) function shall free the memory occupied by the hostent structure pointed to by | 9104 ptr and any structures pointed to from that structure, provided that hostent was obtained by a | 9105 call to getipnodebyaddr( ) or getipnodebyname( ). Applications shall not call freehostent( ) except to 9106 pass it a pointer that was obtained from getipnodebyaddr( ) or getipnodebyname( ). 9107 The gethostent( ) function shall read the next entry in the database, opening and closing a | 9108 connection to the database as necessary. | 9109 The sethostent( ) function shall open a connection to the database and set the next entry for 9110 retrieval to the first entry in the database. If the stayopen argument is non-zero, the connection 9111 shall not be closed by a call to gethostent( ), getipnodebyname( ), gethostbyname( ), getipnodebyaddr( ), 9112 or gethostbyaddr( ), and the implementation may maintain an open file descriptor. | 9113 These functions need not be reentrant. A function that is not required to be reentrant is not | 9114 required to be thread-safe. | 9115 RETURN VALUE 9116 Upon successful completion, the gethostent( ) function shall return a pointer to a hostent 9117 structure if the requested entry was found, and a null pointer if the end of the database was 9118 reached or the requested entry was not found. 9119 ERRORS 9120 No errors are defined for endhostent( ), gethostent( ), and sethostent( ). 9121 EXAMPLES 9122 None. 9123 APPLICATION USAGE 9124 The hostent structure returned by getipnodebyaddr( ) and getipnodebyname( ), and any structures 9125 pointed to from those structures, are dynamically allocated. Applications should call 9126 freehostent( ) to free the memory used by these structures. 9127 The gethostent( ) function may return pointers to static data, which may be overwritten by 9128 subsequent calls to any of these functions. Applications shall not call freehostent( ) for this area. System Interfaces, Issue 6 771 endhostent( ) System Interfaces 9129 RATIONALE 9130 None. 9131 FUTURE DIRECTIONS 9132 None. 9133 SEE ALSO 9134 endservent( ), gethostbyaddr( ), gethostbyname( ), getipnodebyaddr( ), getipnodebyname( ), the Base | 9135 Definitions volume of IEEE Std. 1003.1-200x, | 9136 CHANGE HISTORY 9137 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. | 772 Technical Standard (2000) (Draft July 31, 2000) System Interfaces endnetent( ) 9138 NAME 9139 endnetent, getnetbyaddr, getnetbyname, getnetent, setnetent - network database functions 9140 SYNOPSIS 9141 #include 9142 void endnetent(void); 9143 struct netent *getnetbyaddr(uint32_t net, int type); 9144 struct netent *getnetbyname(const char *name); 9145 struct netent *getnetent(void); 9146 void setnetent(int stayopen); 9147 DESCRIPTION 9148 These functions enable applications to retrieve information about networks. This information is 9149 considered to be stored in a database that can be accessed sequentially or randomly. 9150 Implementation of this database is unspecified. 9151 The endnetent( ) function shall close the database, releasing any open file descriptor. 9152 The getnetbyaddr( ) function shall search the database from the beginning, and find the first entry 9153 for which the address family specified by type matches the n_addrtype member and the network 9154 number net matches the n_net member, opening a connection to the database if necessary. The 9155 net argument shall be the network number in host byte order. 9156 The getnetbyname( ) function shall search the database from the beginning and find the first entry 9157 for which the network name specified by name matches the n_name member, opening and | 9158 closing a connection to the database as necessary. | 9159 The getnetent( ) function shall read the next entry of the database, opening a connection to the 9160 database if necessary. 9161 The setnetent( ) function shall open and rewind the database. If the stayopen argument is non- 9162 zero, the connection to the net database shall not be closed after each call to getnetent( ) (either 9163 directly, or indirectly through one of the other getnet*( ) functions), and the implementation may 9164 maintain an open file descriptor to the database. 9165 The getnetbyaddr( ), getnetbyname( ), and getnetent( ), functions shall each return a pointer to a 9166 netent structure, the members of which shall contain the fields of an entry in the network 9167 database. | 9168 These functions need not be reentrant. A function that is not required to be reentrant is not | 9169 required to be thread-safe. | 9170 RETURN VALUE 9171 Upon successful completion, getnetbyaddr( ), getnetbyname( ), and getnetent( ), shall return a 9172 pointer to a netent structure if the requested entry was found, and a null pointer if the end of the 9173 database was reached or the requested entry was not found. Otherwise, a null pointer shall be 9174 returned. 9175 ERRORS 9176 No errors are defined. System Interfaces, Issue 6 773 endnetent( ) System Interfaces 9177 EXAMPLES 9178 None. 9179 APPLICATION USAGE 9180 The getnetbyaddr( ), getnetbyname( ), and getnetent( ), functions may return pointers to static data, 9181 which may be overwritten by subsequent calls to any of these functions. 9182 RATIONALE 9183 None. 9184 FUTURE DIRECTIONS 9185 None. 9186 SEE ALSO 9187 The Base Definitions volume of IEEE Std. 1003.1-200x, | 9188 CHANGE HISTORY 9189 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. | 774 Technical Standard (2000) (Draft July 31, 2000) System Interfaces endprotoent( ) 9190 NAME 9191 endprotoent, getprotobyname, getprotobynumber, getprotoent, setprotoent - network protocol 9192 database functions 9193 SYNOPSIS 9194 #include 9195 void endprotoent(void); 9196 struct protoent *getprotobyname(const char *name); 9197 struct protoent *getprotobynumber(int proto); 9198 struct protoent *getprotoent(void); 9199 void setprotoent(int stayopen); 9200 DESCRIPTION 9201 These functions enable applications to retrieve information about protocols. This information is 9202 considered to be stored in a database that can be accessed sequentially or randomly. 9203 Implementation of this database is unspecified. 9204 The endprotoent( ) function shall close the connection to the database, releasing any open file 9205 descriptor. 9206 The getprotobyname( ) function shall search the database from the beginning and find the first 9207 entry for which the protocol name specified by name matches the p_name member, opening a 9208 connection to the database if necessary. 9209 The getprotobynumber( ) function shall search the database from the beginning and find the first 9210 entry for which the protocol number specified by proto matches the p_proto member, opening a | 9211 connection to the database if necessary. 9212 The getprotoent( ) function shall read the next entry of the database, opening and closing a | 9213 connection to the database as necessary. | 9214 The setprotoent( ) function shall open a connection to the database, and set the next entry to the 9215 first entry. If the stayopen argument is non-zero, the connection to the network protocol database 9216 shall not be closed after each call to getprotoent( ) (either directly, or indirectly through one of the 9217 other getproto*( ) functions), and the implementation may maintain an open file descriptor for 9218 the database. 9219 The getprotobyname( ), getprotobynumber( ), and getprotoent( ), functions shall each return a pointer 9220 to a protoent structure, the members of which shall contain the fields of an entry in the network 9221 protocol database. | 9222 These functions need not be reentrant. A function that is not required to be reentrant is not | 9223 required to be thread-safe. | 9224 RETURN VALUE 9225 Upon successful completion, getprotobyname( ), getprotobynumber( ), and getprotoent( ) return a 9226 pointer to a protoent structure if the requested entry was found, and a null pointer if the end of 9227 the database was reached or the requested entry was not found. Otherwise, a null pointer is 9228 returned. 9229 ERRORS 9230 No errors are defined. System Interfaces, Issue 6 775 endprotoent( ) System Interfaces 9231 EXAMPLES 9232 None. 9233 APPLICATION USAGE 9234 The getprotobyname( ), getprotobynumber( ), and getprotoent( ) functions may return pointers to 9235 static data, which may be overwritten by subsequent calls to any of these functions. 9236 RATIONALE 9237 None. 9238 FUTURE DIRECTIONS 9239 None. 9240 SEE ALSO 9241 The Base Definitions volume of IEEE Std. 1003.1-200x, | 9242 CHANGE HISTORY 9243 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. | 776 Technical Standard (2000) (Draft July 31, 2000) System Interfaces endpwent( ) 9244 NAME 9245 endpwent, getpwent, setpwent - user database functions 9246 SYNOPSIS 9247 XSI #include 9248 void endpwent(void); 9249 struct passwd *getpwent(void); 9250 void setpwent(void); 9251 9252 DESCRIPTION 9253 The endpwent( ) function may be called to close the user database when processing is complete. | 9254 An implementation that provides extended security controls may impose further | 9255 implementation-defined restrictions on accessing the user database. In particular, the system | 9256 may deny the existence of some or all of the user database entries associated with users other | 9257 than the caller. | 9258 The getpwent( ) function shall return a pointer to a structure containing the broken-out fields of | 9259 an entry in the user database. Each entry in the user database contains a passwd structure. When 9260 first called, getpwent( ) shall return a pointer to a passwd structure containing the first entry in 9261 the user database. Thereafter, it shall return a pointer to a passwd structure containing the next 9262 entry in the user database. Successive calls can be used to search the entire user database. 9263 If an end-of-file or an error is encountered on reading, getpwent( ) shall return a null pointer. 9264 The setpwent( ) function effectively rewinds the user database to allow repeated searches. 9265 These functions need not be reentrant. A function that is not required to be reentrant is not | 9266 required to be thread-safe. 9267 RETURN VALUE 9268 The getpwent( ) function shall return a null pointer on end-of-file or error. 9269 ERRORS 9270 The getpwent( ), setpwent( ), and endpwent( ) functions may fail if: 9271 [EIO] An I/O error has occurred. | 9272 In addition, getpwent( ) and setpwent( ) may fail if: 9273 [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. | 9274 [ENFILE] The maximum allowable number of files is currently open in the system. | 9275 The return value may point to a static area which is overwritten by a subsequent call to 9276 getpwuid( ), getpwnam( ), or getpwent( ). 9277 EXAMPLES 9278 Searching the User Database 9279 The following example uses the getpwent( ) function to get successive entries in the user 9280 database, returning a pointer to a passwd structure that contains information about each user. 9281 The call to endpwent( ) closes the user database and cleans up. 9282 #include 9283 ... 9284 struct passwd *p; 9285 ... System Interfaces, Issue 6 777 endpwent( ) System Interfaces 9286 while ((p = getpwent ()) != NULL) { 9287 ... 9288 } 9289 endpwent(); 9290 ... 9291 APPLICATION USAGE 9292 These functions are provided due to their historical usage. Applications should avoid 9293 dependencies on fields in the password database, whether the database is a single file, or where 9294 in the file system name space the database resides. Applications should use getpwuid( ) 9295 whenever possible because it avoids these dependencies. 9296 RATIONALE 9297 None. 9298 FUTURE DIRECTIONS 9299 None. 9300 SEE ALSO 9301 endgrent( ), getlogin( ), getpwnam( ), getpwuid( ), the Base Definitions volume of | 9302 IEEE Std. 1003.1-200x, | 9303 CHANGE HISTORY 9304 First released in Issue 4, Version 2. 9305 Issue 5 9306 Moved from X/OPEN UNIX extension to BASE. 9307 Normative text previously in the APPLICATION USAGE section is moved to the RETURN 9308 VALUE section. 9309 A note indicating that these functions need not be reentrant is added to the DESCRIPTION. 9310 Issue 6 9311 In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. 778 Technical Standard (2000) (Draft July 31, 2000) System Interfaces endservent( ) 9312 NAME 9313 endservent, getservbyname, getservbyport, getservent, setservent - network services database 9314 functions 9315 SYNOPSIS 9316 #include 9317 void endservent(void); 9318 struct servent *getservbyname(const char *name, const char *proto); 9319 struct servent *getservbyport(int port, const char *proto); 9320 struct servent *getservent(void); 9321 void setservent(int stayopen); 9322 DESCRIPTION 9323 These functions enable applications to retrieve information about network services. This 9324 information is considered to be stored in a database that can be accessed sequentially or 9325 randomly. Implementation of this database is unspecified. 9326 The endservent( ) function shall close the database, releasing any open file descriptor. 9327 The getservbyname( ) function shall search the database from the beginning and find the first 9328 entry for which the service name specified by name matches the s_name member and the protocol 9329 name specified by proto matches the s_proto member, opening a connection to the database if 9330 necessary. If proto is a null pointer, any value of the s_proto member shall be matched. 9331 The getservbyport( ) function shall search the database from the beginning and find the first entry 9332 for which the port specified by port matches the s_port member and the protocol name specified 9333 by proto matches the s_proto member, opening a connection to the database if necessary. If proto 9334 is a null pointer, any value of the s_proto member shall be matched. The port argument shall be in 9335 network byte order. 9336 The getservent( ) function shall read the next entry of the database, opening and closing a | 9337 connection to the database as necessary. | 9338 The setservent( ) function shall open a connection to the database, and set the next entry to the 9339 first entry. If the stayopen argument is non-zero, the net database shall not be closed after each 9340 call to the getservent( ) function (either directly, or indirectly through one of the other getserv*( ) 9341 functions), and the implementation may maintain an open file descriptor for the database. 9342 The getservbyname( ), getservbyport( ), and getservent( ) functions shall each return a pointer to a 9343 servent structure, the members of which shall contain the fields of an entry in the network 9344 services database. | 9345 These functions need not be reentrant. A function that is not required to be reentrant is not | 9346 required to be thread-safe. | 9347 RETURN VALUE 9348 Upon successful completion, getservbyname( ), getservbyport( ), and getservent( ) return a pointer to 9349 a servent structure if the requested entry was found, and a null pointer if the end of the database 9350 was reached or the requested entry was not found. Otherwise, a null pointer is returned. 9351 ERRORS 9352 No errors are defined. System Interfaces, Issue 6 779 endservent( ) System Interfaces 9353 EXAMPLES 9354 None. 9355 APPLICATION USAGE 9356 The port argument of getservbyport( ) need not be compatible with the port values of all address 9357 families. 9358 The getservbyname( ), getservbyport( ), and getservent( ) functions may return pointers to static 9359 data, which may be overwritten by subsequent calls to any of these functions. 9360 RATIONALE 9361 None. 9362 FUTURE DIRECTIONS 9363 None. 9364 SEE ALSO 9365 endhostent( ), endprotoent( ), htonl( ), inet_addr( ), the Base Definitions volume of | 9366 IEEE Std. 1003.1-200x, | 9367 CHANGE HISTORY 9368 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. | 780 Technical Standard (2000) (Draft July 31, 2000) System Interfaces endutxent( ) 9369 NAME 9370 endutxent, getutxent, getutxid, getutxline, pututxline, setutxent - user accounting database 9371 functions 9372 SYNOPSIS 9373 XSI #include 9374 void endutxent(void); 9375 struct utmpx *getutxent(void); 9376 struct utmpx *getutxid(const struct utmpx *id); 9377 struct utmpx *getutxline(const struct utmpx *line); 9378 struct utmpx *pututxline(const struct utmpx *utmpx); 9379 void setutxent(void); 9380 9381 DESCRIPTION 9382 These functions provide access to the user accounting database. 9383 The endutxent( ) function closes the user accounting database. | 9384 An implementation that provides extended security controls may impose further | 9385 implementation-defined restrictions on accessing the user accounting database. In particular, the | 9386 system may deny the existence of some or all of the user accounting database entries associated | 9387 with users other than the caller. | 9388 The getutxent( ) function reads in the next entry from the user accounting database. If the | 9389 database is not already open, it opens it. If it reaches the end of the database, it fails. 9390 The getutxid( ) function searches forward from the current point in the database. If the ut_type 9391 value of the utmpx structure pointed to by id is BOOT_TIME, OLD_TIME, or NEW_TIME, then 9392 it stops when it finds an entry with a matching ut_type value. If the ut_type value is 9393 INIT_PROCESS, LOGIN_PROCESS, USER_PROCESS, or DEAD_PROCESS, then it stops when 9394 it finds an entry whose type is one of these four and whose ut_id member matches the ut_id 9395 member of the utmpx structure pointed to by id. If the end of the database is reached without a 9396 match, getutxid( ) fails. 9397 The getutxid( ) or getutxline( ) function may cache data. For this reason, to use getutxline( ) to 9398 search for multiple occurrences, it is necessary to zero out the static data after each success, or 9399 getutxline( ) could just return a pointer to the same utmpx structure over and over again. 9400 There is one exception to the rule about removing the structure before further reads are done. 9401 The implicit read done by pututxline( ) (if it finds that it is not already at the correct place in the 9402 user accounting database) shall not modify the static structure returned by getutxent( ), 9403 getutxid( ), or getutxline( ), if the application has just modified this structure and passed the 9404 pointer back to pututxline( ). 9405 For all entries that match a request, the ut_type member indicates the type of the entry. Other 9406 members of the entry shall contain meaningful data based on the value of the ut_type member as 9407 follows: System Interfaces, Issue 6 781 endutxent( ) System Interfaces 9408 _________________________________________________________________________ 9409 _ ut_type Member Other Members with Meaningful Data ________________________________________________________________________ 9410 EMPTY No others 9411 BOOT_TIME ut_tv 9412 OLD_TIME ut_tv 9413 NEW_TIME ut_tv 9414 USER_PROCESS ut_id, ut_user (login name of the user), ut_line, ut_pid, ut_tv 9415 INIT_PROCESS ut_id, ut_pid, ut_tv 9416 LOGIN_PROCESS ut_id, ut_user (implementation-defined name of the login 9417 process), ut_pid, ut_tv 9418 _ DEAD_PROCESS ut_id, ut_pid, ut_tv ________________________________________________________________________ 9419 The getutxline( ) function searches forward from the current point in the database until it finds an 9420 entry of the type LOGIN_PROCESS or USER_PROCESS which also has a ut_line value matching 9421 that in the utmpx structure pointed to by line. If the end of the database is reached without a 9422 match, getutxline( ) fails. 9423 If the process has appropriate privileges, the pututxline( ) function writes out the structure into 9424 the user accounting database. It uses getutxid( ) to search for a record that satisfies the request. If 9425 this search succeeds, then the entry is replaced. Otherwise, a new entry is made at the end of the 9426 user accounting database. 9427 The setutxent( ) function resets the input to the beginning of the database. This should be done 9428 before each search for a new entry if it is desired that the entire database be examined. 9429 These functions need not be reentrant. A function that is not required to be reentrant is not | 9430 required to be thread-safe. 9431 RETURN VALUE 9432 Upon successful completion, getutxent( ), getutxid( ), and getutxline( ) shall return a pointer to a 9433 utmpx structure containing a copy of the requested entry in the user accounting database. 9434 Otherwise, a null pointer shall be returned. 9435 The return value may point to a static area which is overwritten by a subsequent call to 9436 getutxid( ) or getutxline( ). 9437 Upon successful completion, pututxline( ) shall return a pointer to a utmpx structure containing a 9438 copy of the entry added to the user accounting database. Otherwise, a null pointer shall be 9439 returned. 9440 The endutxent( ) and setutxent( ) functions shall return no value. 9441 ERRORS 9442 No errors are defined for the endutxent( ), getutxent( ), getutxid( ), getutxline( ), and setutxent( ) 9443 functions. 9444 The pututxline( ) function may fail if: 9445 [EPERM] The process does not have appropriate privileges. | 782 Technical Standard (2000) (Draft July 31, 2000) System Interfaces endutxent( ) 9446 EXAMPLES 9447 None. 9448 APPLICATION USAGE 9449 The sizes of the arrays in the structure can be found using the sizeof operator. 9450 RATIONALE 9451 None. 9452 FUTURE DIRECTIONS 9453 None. 9454 SEE ALSO 9455 The Base Definitions volume of IEEE Std. 1003.1-200x, | 9456 CHANGE HISTORY 9457 First released in Issue 4, Version 2. 9458 Issue 5 9459 Moved from X/OPEN UNIX extension to BASE. 9460 Normative text previously in the APPLICATION USAGE section is moved to the 9461 DESCRIPTION. 9462 A note indicating that these functions need not be reentrant is added to the DESCRIPTION. 9463 Issue 6 9464 In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. System Interfaces, Issue 6 783 environ System Interfaces 9465 NAME 9466 environ - array of character pointers to the environment strings 9467 SYNOPSIS 9468 extern char **environ; 9469 DESCRIPTION 9470 Refer to the Base Definitions volume of IEEE Std. 1003.1-200x, Chapter 8, Environment Variables | 9471 and exec. | 784 Technical Standard (2000) (Draft July 31, 2000) System Interfaces erand48( ) 9472 NAME 9473 erand48 - generate uniformly distributed pseudo-random numbers 9474 SYNOPSIS 9475 XSI #include 9476 double erand48(unsigned short xsubi[3]); | 9477 | 9478 DESCRIPTION 9479 Refer to drand48( ). System Interfaces, Issue 6 785 erf( ) System Interfaces 9480 NAME 9481 erf, erfc, erfcf, erfcl, erff, erfl - error and complementary error functions | 9482 SYNOPSIS 9483 XSI #include 9484 double erf(double x); 9485 double erfc(double x); 9486 float erfcf(float x); | 9487 long double erfcl(long double x); | 9488 float erff(float x); | 9489 long double erfl(long double x); | 9490 | 9491 DESCRIPTION 9492 The erf( ), erff,( ) and erfl( ) functions shall compute the error function of x, defined as: | x _2 ___ e-t2dt 9493 0 9494 The erfc( ), erfcf( ), and erfcl( ) functions shall compute 1.0 - erf(x). | 9495 An application wishing to check for error situations should set errno to 0 before calling erf( ). If 9496 errno is non-zero on return, or the return value is NaN, an error has occurred. 9497 RETURN VALUE 9498 Upon successful completion, these functions shall return the value of the error function and | 9499 complementary error function, respectively. | 9500 If x is NaN, NaN shall be returned and errno may be set to [EDOM]. | 9501 If the correct value would cause underflow, 0 shall be returned and errno may be set to 9502 [ERANGE]. | 9503 ERRORS 9504 The erfc( ), erfcf( ), and erfcl( ) functions shall fail if: | 9505 [ERANGE] The value of x is too large. | 9506 The erf( ) and erfc( ) functions may fail if: | 9507 [EDOM] The value of x is NaN. | 9508 [ERANGE] The result underflows | 9509 No other errors shall occur. 9510 EXAMPLES 9511 None. 9512 APPLICATION USAGE 9513 The erfc( ) function is provided because of the extreme loss of relative accuracy if erf(x) is called 9514 for large x and the result subtracted from 1.0. 9515 RATIONALE 9516 None. 9517 FUTURE DIRECTIONS 9518 None. 786 Technical Standard (2000) (Draft July 31, 2000) System Interfaces erf( ) 9519 SEE ALSO 9520 isnan( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 9521 CHANGE HISTORY 9522 First released in Issue 1. Derived from Issue 1 of the SVID. | 9523 Issue 4 9524 References to matherr( ) are removed. 9525 The RETURN VALUE and ERRORS sections are substantially rewritten to rationalize error 9526 handling in the mathematics functions. 9527 Issue 5 9528 The DESCRIPTION is updated to indicate how an application should check for an error. This 9529 text was previously published in the APPLICATION USAGE section. | 9530 Issue 6 | 9531 The erfcf( ), erfcl( ), erff( ), and erfl( ) functions are added for alignment with the | 9532 ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 787 errno System Interfaces 9533 NAME 9534 errno - error return value | 9535 SYNOPSIS 9536 #include 9537 DESCRIPTION 9538 errno is used by many functions to return error values. 9539 Many functions provide an error number in errno which has type int and is defined in . 9540 The value of errno shall be defined only after a call to a function for which it is explicitly stated to 9541 be set and until it is changed by the next function call. The value of errno should only be 9542 examined when it is indicated to be valid by a function's return value. Programs should obtain 9543 the definition of errno by the inclusion of . No function in this volume of | 9544 IEEE Std. 1003.1-200x shall set errno to 0. | 9545 It is unspecified whether errno is a macro or an identifier declared with external linkage. If a 9546 macro definition is suppressed in order to access an actual object, or a program defines an 9547 identifier with the name errno, the behavior is undefined. 9548 The symbolic values stored in errno are documented in the ERRORS sections on all relevant 9549 pages. 9550 RETURN VALUE 9551 None. 9552 ERRORS 9553 None. 9554 EXAMPLES 9555 None. 9556 APPLICATION USAGE 9557 Previously both POSIX and X/Open documents were more restrictive than the ISO C standard 9558 in that they required errno to be defined as an external variable, whereas the ISO C standard 9559 required only that errno be defined as a modifiable lvalue with type int. 9560 A program that uses errno for error checking should set it to 0 before a function call, then inspect 9561 it before a subsequent function call. 9562 RATIONALE 9563 None. 9564 FUTURE DIRECTIONS 9565 None. 9566 SEE ALSO 9567 Section 2.3, the Base Definitions volume of IEEE Std. 1003.1-200x, | 9568 CHANGE HISTORY 9569 First released in Issue 1. Derived from Issue 1 of the SVID. | 9570 Issue 4 9571 The FUTURE DIRECTIONS section is deleted. 9572 The following changes are incorporated for alignment with the ISO C standard: 9573 * The DESCRIPTION now guarantees that errno is set to 0 at program start-up, and that it is 9574 never reset to 0 by any XSI function. 788 Technical Standard (2000) (Draft July 31, 2000) System Interfaces errno 9575 * The APPLICATION USAGE section is added. This issue is aligned with the ISO C standard, 9576 which permits errno to be a macro. 9577 Issue 5 9578 The following sentence is deleted from the DESCRIPTION: ``The value of errno is 0 at program 9579 start-up, but is never set to 0 by any XSI function''. The DESCRIPTION also no longer states that 9580 conforming implementations may support the declaration: 9581 extern int errno; 9582 Issue 6 | 9583 Obsolescent text regarding defining errno as: | 9584 extern int errno | 9585 is removed. | 9586 Text regarding no function setting errno to zero to indicate an error is changed to no function | 9587 shall set errno to zero. This is for alignment with the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 789 exec System Interfaces 9588 NAME 9589 environ, execl, execv, execle, execve, execlp, execvp - execute a file 9590 SYNOPSIS 9591 #include 9592 extern char **environ; 9593 int execl(const char *path, const char *arg0, ... /*, (char *)0 */); 9594 int execv(const char *path, char *const argv[]); 9595 int execle(const char *path, const char *arg0, ... /*, 9596 (char *)0, char *const envp[]*/); 9597 int execve(const char *path, char *const argv[], char *const envp[]); 9598 int execlp(const char *file, const char *arg0, ... /*, (char *)0 */); 9599 int execvp(const char *file, char *const argv[]); 9600 DESCRIPTION 9601 The exec functions shall replace the current process image with a new process image. The new 9602 image is constructed from a regular, executable file called the new process image file. There shall 9603 be no return from a successful exec, because the calling process image is overlaid by the new 9604 process image. 9605 When a C-language program is executed as a result of this call, it shall be entered as a C- 9606 language function call as follows: 9607 int main (int argc, char *argv[]); 9608 where argc is the argument count and argv is an array of character pointers to the arguments 9609 themselves. In addition, the following variable: 9610 extern char **environ; 9611 is initialized as a pointer to an array of character pointers to the environment strings. The argv 9612 and environ arrays are each terminated by a null pointer. The null pointer terminating the argv 9613 array is not counted in argc. 9614 THR Conforming multi-threaded applications shall not use the environ variable to access or modify 9615 any environment variable while any other thread is concurrently modifying any environment 9616 variable. A call to any function dependent on any environment variable shall be considered a use 9617 of the environ variable to access that environment variable. 9618 The arguments specified by a program with one of the exec functions shall be passed on to the 9619 new process image in the corresponding main( ) arguments. 9620 The argument path points to a path name that identifies the new process image file. 9621 The argument file is used to construct a path name that identifies the new process image file. If 9622 the file argument contains a slash character, the file argument shall be used as the path name for 9623 this file. Otherwise, the path prefix for this file is obtained by a search of the directories passed 9624 as the environment variable PATH (see the Base Definitions volume of IEEE Std. 1003.1-200x, | 9625 Chapter 8, Environment Variables). If this environment variable is not present, the results of the | 9626 search are implementation-defined. | 9627 If the process image file is not a valid executable object, execlp( ) and execvp( ) shall use the | 9628 contents of that file as standard input to a command interpreter conforming to system( ). In this | 9629 case, the command interpreter becomes the new process image. 9630 The arguments represented by arg0,. . . are pointers to null-terminated character strings. These 9631 strings constitute the argument list available to the new process image. The list is terminated by 9632 a null pointer. The argument arg0 should point to a file name that is associated with the process 790 Technical Standard (2000) (Draft July 31, 2000) System Interfaces exec 9633 being started by one of the exec functions. 9634 The argument argv is an array of character pointers to null-terminated strings. The application 9635 shall ensure that the last member of this array is a null pointer. These strings constitute the 9636 argument list available to the new process image. The value in argv[0] should point to a file 9637 name that is associated with the process being started by one of the exec functions. 9638 The argument envp is an array of character pointers to null-terminated strings. These strings 9639 constitute the environment for the new process image. The envp array is terminated by a null 9640 pointer. 9641 For those forms not containing an envp pointer (execl( ), execv( ), execlp( ), and execvp( )), the 9642 environment for the new process image is taken from the external variable environ in the calling 9643 process. 9644 The number of bytes available for the new process' combined argument and environment lists is 9645 {ARG_MAX}. It is implementation-defined whether null terminators, pointers, and/or any | 9646 alignment bytes are included in this total. 9647 File descriptors open in the calling process image remain open in the new process image, except 9648 for those whose close-on-exec flag FD_CLOEXEC is set. For those file descriptors that remain 9649 open, all attributes of the open file description remain unchanged. For any file descriptor that is 9650 closed for this reason, file locks are removed as a result of the close as described in close( ). Locks 9651 that are not removed by closing of file descriptors remain unchanged. 9652 Directory streams open in the calling process image shall be closed in the new process image. 9653 XSI The state of conversion descriptors and message catalog descriptors in the new process image is 9654 undefined. For the new process, the equivalent of: 9655 setlocale(LC_ALL, "C") 9656 is executed at start-up. 9657 Signals set to the default action (SIG_DFL) in the calling process image shall be set to the default 9658 action in the new process image. Signals set to be ignored (SIG_IGN) by the calling process 9659 image shall be set to be ignored by the new process image. Signals set to be caught by the calling 9660 XSI process image shall be set to the default action in the new process image (see ). After 9661 a successful call to any of the exec functions, alternate signal stacks are not preserved and the 9662 SA_ONSTACK flag shall be cleared for all signals. 9663 After a successful call to any of the exec functions, any functions previously registered by atexit( ) 9664 are no longer registered. 9665 XSI If the ST_NOSUID bit is set for the file system containing the new process image file, then the 9666 effective user ID, effective group ID, saved set-user-ID, and saved set-group-ID are unchanged 9667 in the new process image. Otherwise,if the set-user-ID mode bit of the new process image file is 9668 set, the effective user ID of the new process image is set to the user ID of the new process image 9669 file. Similarly, if the set-group-ID mode bit of the new process image file is set, the effective 9670 group ID of the new process image is set to the group ID of the new process image file. The real 9671 user ID, real group ID, and supplementary group IDs of the new process image remain the same 9672 as those of the calling process image. The effective user ID and effective group ID of the new 9673 process image shall be saved (as the saved set-user-ID and the saved set-group-ID) for use by 9674 setuid( ). 9675 XSI Any shared memory segments attached to the calling process image shall not be attached to the 9676 new process image. System Interfaces, Issue 6 791 exec System Interfaces 9677 SEM Any named semaphores open in the calling process shall be closed as if by appropriate calls to 9678 sem_close( ). 9679 TYM Any blocks of typed memory that were mapped in the calling process are unmapped, as if 9680 munmap( ) was implicitly called to unmap them. 9681 ML Memory locks established by the calling process via calls to mlockall( ) or mlock( ) shall be 9682 removed. If locked pages in the address space of the calling process are also mapped into the 9683 address spaces of other processes and are locked by those processes, the locks established by the 9684 other processes shall be unaffected by the call by this process to the exec function. If the exec 9685 function fails, the effect on memory locks is unspecified. 9686 MF|SHM Memory mappings created in the process are unmapped before the address space is rebuilt for 9687 the new process image. 9688 PS For the SCHED_FIFO and SCHED_RR scheduling policies, the policy and priority settings shall 9689 not be changed by a call to an exec function. For other scheduling policies, the policy and priority 9690 settings on exec are implementation-defined. | 9691 TMR Per-process timers created by the calling process shall be deleted before replacing the current 9692 process image with the new process image. 9693 MSG All open message queue descriptors in the calling process shall be closed, as described in 9694 mq_close( ). 9695 AIO Any outstanding asynchronous I/O operations may be canceled. Those asynchronous I/O 9696 operations that are not canceled shall complete as if the exec function had not yet occurred, but 9697 any associated signal notifications shall be suppressed. It is unspecified whether the exec 9698 function itself blocks awaiting such I/O completion. In no event, however, shall the new process 9699 image created by the exec function be affected by the presence of outstanding asynchronous I/O 9700 operations at the time the exec function is called. Whether any I/O is canceled, and which I/O 9701 may be canceled upon exec, is implementation-defined. | 9702 CPT The new process image shall inherit the CPU-time clock of the calling process image. This | 9703 inheritance means that the process CPU-time clock of the process being execed shall not be | 9704 reinitialized or altered as a result of the exec function other than to reflect the time spent by the 9705 process executing the exec function itself. 9706 TCT The initial value of the CPU-time clock of the initial thread of the new process image shall be set 9707 to zero. 9708 TRC If the calling process is being traced, the new process image continues to be traced into the same | 9709 trace stream as the original process image, but the new process image shall not inherit the | 9710 mapping of trace event names to trace event type identifiers that was defined by calls to the | 9711 posix_trace_eventid_open( ) or the posix_trace_trid_eventid_open( ) functions in the calling process | 9712 image. | 9713 If the calling process is a trace controller process, any trace streams that were created by the | 9714 calling process shall be shut down as described in the posix_trace_shutdown( ) function. | 9715 The new process also inherits at least the following attributes from the calling process image: | 9716 XSI * Nice value (see nice( )) 9717 XSI * semadj values (see semop( )) 9718 * Process ID 9719 * Parent process ID 792 Technical Standard (2000) (Draft July 31, 2000) System Interfaces exec 9720 * Process group ID 9721 * Session membership 9722 * Real user ID 9723 * Real group ID 9724 * Supplementary group IDs 9725 * Time left until an alarm clock signal (see alarm( )) 9726 * Current working directory 9727 * Root directory 9728 * File mode creation mask (see umask( )) 9729 XSI * File size limit (see ulimit( )) 9730 * Process signal mask (see sigprocmask( )) 9731 * Pending signal (see sigpending( )) 9732 * tms_utime, tms_stime, tms_cutime, and tms_cstime (see times( )) 9733 XSI * Resource limits 9734 XSI * Controlling terminal 9735 XSI * Interval timers 9736 All other process attributes defined in this volume of IEEE Std. 1003.1-200x shall be the same in 9737 the new and old process images. The inheritance of process attributes not defined by this | 9738 volume of IEEE Std. 1003.1-200x is implementation-defined. | 9739 A call to any exec function from a process with more than one thread results in all threads being 9740 terminated and the new executable image being loaded and executed. No destructor functions 9741 shall be called. 9742 Upon successful completion, the exec functions shall mark for update the st_atime field of the file. 9743 If an exec function failed but was able to locate the process image file, whether the st_atime field is 9744 marked for update is unspecified. Should the exec function succeed, the process image file shall 9745 be considered to have been opened with open( ). The corresponding close( ) shall be considered 9746 to occur at a time after this open, but before process termination or successful completion of a 9747 subsequent call to one of the exec functions. The argv[ ] and envp[ ] arrays of pointers and the 9748 strings to which those arrays point shall not be modified by a call to one of the exec functions, 9749 except as a consequence of replacing the process image. 9750 XSI The saved resource limits in the new process image are set to be a copy of the process' 9751 corresponding hard and soft limits. 9752 RETURN VALUE 9753 If one of the exec functions returns to the calling process image, an error has occurred; the return 9754 value shall be -1, and errno shall be set to indicate the error. 9755 ERRORS 9756 The exec functions shall fail if: 9757 [E2BIG] The number of bytes used by the new process image's argument list and | 9758 environment list is greater than the system-imposed limit of {ARG_MAX} 9759 bytes. System Interfaces, Issue 6 793 exec System Interfaces 9760 [EACCES] Search permission is denied for a directory listed in the new process image | 9761 file's path prefix, or the new process image file denies execution permission, 9762 or the new process image file is not a regular file and the implementation does 9763 not support execution of files of its type. 9764 [EINVAL] The new process image file has the appropriate permission and has a 9765 recognized executable binary format, but the system does not support 9766 execution of a file with this format. 9767 [ELOOP] A loop exists in symbolic links encountered during resolution of the path or file | 9768 argument. 9769 [ENAMETOOLONG] | 9770 The length of the path or file arguments exceeds {PATH_MAX} or a path name | 9771 component is longer than {NAME_MAX}. | 9772 [ENOENT] A component of path or file does not name an existing file or path or file is an | 9773 empty string. 9774 [ENOTDIR] A component of the new process image file's path prefix is not a directory. | 9775 The exec functions, except for execlp( ) and execvp( ), shall fail if: 9776 [ENOEXEC] The new process image file has the appropriate access permission but has an | 9777 unrecognized format. 9778 The exec functions may fail if: 9779 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 9780 resolution of the path or file argument. 9781 [ENAMETOOLONG] | 9782 As a result of encountering a symbolic link in resolution of the path argument, 9783 the length of the substituted path name string exceeded {PATH_MAX}. 9784 [ENOMEM] The new process image requires more memory than is allowed by the | 9785 hardware or system-imposed memory management constraints. 9786 [ETXTBSY] The new process image file is a pure procedure (shared text) file that is | 9787 currently open for writing by some process. 9788 EXAMPLES 9789 Using execl( ) 9790 The following example executes the ls command, specifying the path name of the executable 9791 (/bin/ls) and using arguments supplied directly to the command to produce single-column 9792 output. 9793 #include 9794 int ret; 9795 ... 9796 ret = execl ("/bin/ls", "ls", "-1", NULL); 794 Technical Standard (2000) (Draft July 31, 2000) System Interfaces exec 9797 Using execle( ) 9798 The following example is similar to Using execl( ) (on page 794). In addition, it specifies the 9799 environment for the new process image using the env argument. 9800 #include 9801 int ret; 9802 char *env[] = { "HOME=/usr/home", "LOGNAME=home", NULL }; 9803 ... 9804 ret = execle ("/bin/ls", "ls", "-l", NULL, env); 9805 Using execlp( ) 9806 The following example searches for the location of the ls command among the directories 9807 specified by the PATH environment variable. 9808 #include 9809 int ret; 9810 ... 9811 ret = execlp ("ls", "ls", "-l", NULL); 9812 Using execv( ) 9813 The following example passes arguments to the ls command in the cmd array. 9814 #include 9815 int ret; 9816 char *cmd[] = { "ls", "-l", NULL }; 9817 ... 9818 ret = execv ("/bin/ls", cmd); 9819 Using execve( ) 9820 The following example passes arguments to the ls command in the cmd array, and specifies the 9821 environment for the new process image using the env argument. 9822 #include 9823 int ret; 9824 char *cmd[] = { "ls", "-l", NULL }; 9825 char *env[] = { "HOME=/usr/home", "LOGNAME=home", NULL }; 9826 ... 9827 ret = execve ("/bin/ls", cmd, env); 9828 Using execvp( ) 9829 The following example searches for the location of the ls command among the directories 9830 specified by the PATH environment variable, and passes arguments to the ls command in the 9831 cmd array. 9832 #include 9833 int ret; 9834 char *cmd[] = { "ls", "-l", NULL }; 9835 ... System Interfaces, Issue 6 795 exec System Interfaces 9836 ret = execvp ("ls", cmd); 9837 APPLICATION USAGE 9838 As the state of conversion descriptors and message catalog descriptors in the new process image 9839 is undefined, portable applications should not rely on their use and should close them prior to 9840 calling one of the exec functions. 9841 Applications that require other than the default POSIX locale should call setlocale( ) with the 9842 appropriate parameters to establish the locale of the new process. 9843 The environ array should not be accessed directly by the application. 9844 RATIONALE 9845 Early proposals required that the value of argc passed to main( ) be ``one or greater''. This was 9846 driven by the same requirement in drafts of the ISO C standard. In fact, historical 9847 implementations have passed a value of zero when no arguments are supplied to the caller of 9848 the exec functions. This requirement was removed from the ISO C standard and subsequently 9849 removed from this volume of IEEE Std. 1003.1-200x as well. The wording, in particular the use of 9850 the word should, requires a Strictly Conforming POSIX Application to pass at least one argument 9851 to the exec function, thus guaranteeing that argc be one or greater when invoked by such an 9852 application. In fact, this is good practice, since many existing applications reference argv[0] 9853 without first checking the value of argc. 9854 The requirement on a Strictly Conforming POSIX Application also states that the value passed 9855 as the first argument be a file name associated with the process being started. Although some 9856 existing applications pass a path name rather than a file name in some circumstances, a file 9857 name is more generally useful, since the common usage of argv[0] is in printing diagnostics. In 9858 some cases the file name passed is not the actual file name of the file; for example, many 9859 implementations of the login utility use a convention of prefixing a hyphen ('-') to the actual 9860 file name, which indicates to the command interpreter being invoked that it is a ``login shell''. 9861 Some systems can exec shell scripts. | 9862 One common historical implementation is that the execl( ), execv( ), execle( ), and execve( ) 9863 functions return an [ENOEXEC] error for any file not recognizable as executable, including a 9864 shell script. When the execlp( ) and execvp( ) functions encounter such a file, they assume the file 9865 to be a shell script and invoke a known command interpreter to interpret such files. These 9866 implementations of execvp( ) and execlp( ) only give the [ENOEXEC] error in the rare case of a 9867 problem with the command interpreter's executable file. Because of these implementations, the 9868 [ENOEXEC] error is not mentioned for execlp( ) or execvp( ), although implementations can still 9869 give it. 9870 Another way that some historical implementations handle shell scripts is by recognizing the first 9871 two bytes of the file as the character string "#!" and using the remainder of the first line of the 9872 file as the name of the command interpreter to execute. 9873 Some implementations provide a third argument to main( ) called envp. This is defined as a 9874 pointer to the environment. The ISO C standard specifies invoking main( ) with two arguments, 9875 so implementations must support applications written this way. Since this volume of 9876 IEEE Std. 1003.1-200x defines the global variable environ, which is also provided by historical 9877 implementations and can be used anywhere that envp could be used, there is no functional need 9878 for the envp argument. Applications should use the getenv( ) function rather than accessing the 9879 environment directly via either envp or environ. Implementations are required to support the 9880 two-argument calling sequence, but this does not prohibit an implementation from supporting 9881 envp as an optional third argument. 796 Technical Standard (2000) (Draft July 31, 2000) System Interfaces exec 9882 This volume of IEEE Std. 1003.1-200x specifies that signals set to SIG_IGN remain set to 9883 SIG_IGN, and that the process signal mask be unchanged across an exec. This is consistent with 9884 historical implementations, and it permits some useful functionality, such as the nohup 9885 command. However, it should be noted that many existing applications wrongly assume that 9886 they start with certain signals set to the default action and/or unblocked. In particular, 9887 applications written with a simpler signal model that does not include blocking of signals, such 9888 as the one in the ISO C standard, may not behave properly if invoked with some signals blocked. 9889 Therefore, it is best not to block or ignore signals across execs without explicit reason to do so, 9890 and especially not to block signals across execs of arbitrary (not closely co-operating) programs. 9891 The exec functions always save the value of the effective user ID and effective group ID of the 9892 process at the completion of the exec, whether or not the set-user-ID or the set-group-ID bit of 9893 the process image file is set. 9894 The statement about argv[ ] and envp[ ] being constants is included to make explicit to future 9895 writers of language bindings that these objects are completely constant. Due to a limitation of 9896 the ISO C standard, it is not possible to state that idea in standard C. Specifying two levels of 9897 const-qualification for the argv[ ] and envp[ ] parameters for the exec functions may seem to be the 9898 natural choice, given that these functions do not modify either the array of pointers or the 9899 characters to which the function points, but this would disallow existing correct code. Instead, 9900 only the array of pointers is noted as constant. The table of assignment compatibility for dst=src, 9901 derived from the ISO C standard summarizes the compatibility: _______________________________________________________________________________ 9902 _ dst: char *[ ] const char *[ ] char *const[ ] const char *const[ ] ______________________________________________________________________________ 9903 src: 9904 char *[ ] VALID - VALID - 9905 const char *[ ] - VALID - VALID 9906 char * const [ ] - - VALID - 9907 _ const char *const[ ] - - - VALID ______________________________________________________________________________ 9908 Since all existing code has a source type matching the first row, the column that gives the most 9909 valid combinations is the third column. The only other possibility is the fourth column, but 9910 using it would require a cast on the argv or envp arguments. It is unfortunate that the fourth 9911 column cannot be used, because the declaration a non-expert would naturally use would be that 9912 in the second row. 9913 The ISO C standard and this volume of IEEE Std. 1003.1-200x do not conflict on the use of 9914 environ, but some historical implementations of environ may cause a conflict. As long as environ 9915 is treated in the same way as an entry point (for example, fork( )), it conforms to both standards. 9916 A library can contain fork( ), but if there is a user-provided fork( ), that fork( ) is given precedence 9917 and no problem ensues. The situation is similar for environ: the definition in this volume of 9918 IEEE Std. 1003.1-200x is to be used if there is no user-provided environ to take precedence. At 9919 least three implementations are known to exist that solve this problem. 9920 [E2BIG] The limit {ARG_MAX} applies not just to the size of the argument list, but to | 9921 the sum of that and the size of the environment list. 9922 [EFAULT] Some historical systems return [EFAULT] rather than [ENOEXEC] when the 9923 new process image file is corrupted. They are non-conforming. 9924 [EINVAL] This error condition was added to IEEE Std. 1003.1-200x to allow an 9925 implementation to detect executable files generated for different architectures, 9926 and indicate this situation to the application. Historical implementations of 9927 shells, execvp( ), and execlp( ) that encounter an [ENOEXEC] error will execute 9928 a shell on the assumption that the file is a shell script. This will not produce 9929 the desired effect when the file is a valid executable for a different System Interfaces, Issue 6 797 exec System Interfaces 9930 architecture. An implementation may now choose to avoid this problem by 9931 returning [EINVAL] when a valid executable for a different architecture is 9932 encountered. Some historical implementations return [EINVAL] to indicate 9933 that the path argument contains a character with the high order bit set. The 9934 standard developers chose to deviate from historical practice for the following 9935 reasons: 9936 1. The new utilization of [EINVAL] will provide some measure of utility to 9937 the user community. 9938 2. Historical use of [EINVAL] is not acceptable in an internationalized 9939 operating environment. 9940 [ENAMETOOLONG] | 9941 Since the file path name may be constructed by taking elements in the PATH 9942 variable and putting them together with the file name, the 9943 [ENAMETOOLONG] error condition could also be reached this way. 9944 [ETXTBSY] System V returns this error when the executable file is currently open for | 9945 writing by some process. This volume of IEEE Std. 1003.1-200x neither 9946 requires nor prohibits this behavior. 9947 Other systems (such as System V) may return [EINTR] from exec. This is not addressed by this | 9948 volume of IEEE Std. 1003.1-200x, but implementations may have a window between the call to 9949 exec and the time that a signal could cause one of the exec calls to return with [EINTR]. 9950 FUTURE DIRECTIONS 9951 None. 9952 SEE ALSO 9953 alarm( ), atexit( ), chmod( ), close( ), exit( ), fcntl( ), fork( ), fstatvfs( ), getenv( ), getitimer( ), getrlimit( ), 9954 mmap( ), nice( ), (posix_trace_eventid), posix_trace_shutdown( ), | 9955 posix_trace_trid_eventid_open( ), putenv( ), semop( ), setlocale( ), shmat( ), sigaction( ), sigaltstack( ), | 9956 sigpending( ), sigprocmask( ), system( ), times( ), ulimit( ), umask( ), the Base Definitions volume of | 9957 IEEE Std. 1003.1-200x, , the Base Definitions volume of IEEE Std. 1003.1-200x, Chapter | 9958 11, General Terminal Interface | 9959 CHANGE HISTORY 9960 First released in Issue 1. Derived from Issue 1 of the SVID. | 9961 Issue 4 9962 The header is added to the SYNOPSIS section. 9963 The const keyword is added to identifiers of constant type (for example, path, file). 9964 In the DESCRIPTION: 9965 * An indication of the disposition of conversion descriptors after a call to one of the exec 9966 functions is added. 9967 * A statement about the interaction between exec and atexit( ) is added. 9968 * usually in the descriptions of argument pointers is removed. 9969 * owner ID is changed to user ID. 9970 * Shared memory is no longer optional. 9971 * The penultimate paragraph is changed to correct an error in Issue 3. It now refers to ``All 9972 other process attributes . . .'' instead of ``All the process attributes . . .'' 798 Technical Standard (2000) (Draft July 31, 2000) System Interfaces exec 9973 A note about the initialization of locales is added to the APPLICATION USAGE section. 9974 The following change is incorporated for alignment with the ISO POSIX-1 standard: 9975 * In the ERRORS section, the description of the [ENOEXEC] error is changed to indicate that | 9976 this error does not apply to execlp( ) and execvp( ), and the [ENOMEM] error is added. | 9977 The following change is incorporated for alignment with the FIPS requirements: 9978 * In the ERRORS section, the condition whereby [ENAMETOOLONG] is returned if a path | 9979 name component is larger that {NAME_MAX} is now defined as mandatory and marked as 9980 an extension. 9981 Issue 4, Version 2 9982 The following changes are incorporated for X/OPEN UNIX conformance: 9983 * The DESCRIPTION is changed: 9984 - To indicate the disposition of alternate signal stacks, the SA_ONSTACK flag, and 9985 mappings established through mmap( ) after a successful call to one of the exec functions. 9986 - The effects of ST_NOSUID being set for a file system are defined. 9987 - A statement is added that mappings established through mmap( ) are not preserved across 9988 an exec. 9989 - The list of inherited process attributes is extended to include resource limits, the 9990 controlling terminal, and interval timers. 9991 * In the ERRORS section: 9992 - The condition whereby [ELOOP] is returned if too many symbolic links are encountered 9993 during path name resolution is defined as mandatory. 9994 - A second [ENAMETOOLONG] condition is defined that may report excessive length of 9995 an intermediate result of path name resolution of a symbolic link. 9996 Issue 5 9997 The DESCRIPTION is updated for alignment with the POSIX Realtime Extension and the POSIX 9998 Threads Extension. 9999 Large File Summit extensions are added. 10000 Issue 6 10001 The following changes are made for alignment with the ISO POSIX-1: 1996 standard: 10002 * The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. 10003 This is since behavior may vary from one file system to another. 10004 The following new requirements on POSIX implementations derive from alignment with the 10005 Single UNIX Specification: 10006 * In the DESCRIPTION, behavior is defined for when the process image file is not a valid 10007 executable. 10008 * In this issue, _POSIX_SAVED_IDS is mandated, thus the effective user ID and effective group 10009 ID of the new process image shall be saved (as the saved set-user-ID and the saved set- 10010 group-ID) for use by the setuid( ) function. 10011 * The [ELOOP] mandatory error condition is added. 10012 * A second [ENAMETOOLONG] is added as an optional error condition. System Interfaces, Issue 6 799 exec System Interfaces 10013 * The [ETXTBSY] optional error condition is added. 10014 The following changes were made to align with the IEEE P1003.1a draft standard: 10015 * The [EINVAL] mandatory error condition is added. 10016 * The [ELOOP] optional error condition is added. 10017 The description of CPU-time clock semantics is added for alignment with 10018 IEEE Std. 1003.1d-1999. 10019 The DESCRIPTION is updated for alignment with IEEE Std. 1003.1j-2000 by adding semantics 10020 for typed memory. 10021 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. | 10022 The description of tracing semantics is added for alignment with IEEE Std. 1003.1q-2000. | 800 Technical Standard (2000) (Draft July 31, 2000) System Interfaces exit( ) 10023 NAME 10024 exit, _Exit, _exit - terminate a process | 10025 SYNOPSIS 10026 #include 10027 void exit(int status); 10028 #include 10029 void _Exit(int status); | 10030 void _exit(int status); | 10031 DESCRIPTION 10032 CX The functionality described on this reference page for the exit( ) function is aligned with the 10033 ISO C standard. Any conflict between the requirements described here and the ISO C standard 10034 are unintentional. This volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 10035 The exit( ) function shall first call all functions registered by atexit( ), in the reverse order of their | 10036 registration, except that a function is called after any previously registered functions that had | 10037 already been called at the time it was registered. Each function is called as many times as it was | 10038 registered. If, during the call to any such function, a call to the longjmp( ) function is made that | 10039 would terminate the call to the registered function, the behavior is undefined. | 10040 If a function registered by a call to atexit( ) fails to return, the remaining registered functions shall 10041 not be called and the rest of the exit( ) processing shall not be completed. If exit( ) is called more 10042 than once, the effects are undefined. 10043 CX The exit( ) function then flushes all output streams, closes all open streams, and removes all files 10044 created by tmpfile( ). Finally, control is returned to the host environment as described below. The 10045 values of status can be EXIT_SUCCESS or EXIT_FAILURE, as described in , or any | 10046 CX implementation-defined value, although note that only the range 0 through 255 shall be | 10047 available to a waiting parent process. 10048 The _Exit( ) and _exit( ) functions shall be functionally identical. | 10049 CX The _Exit( ), _exit( ), and exit( ) functions shall terminate the calling process with the following | 10050 consequences: 10051 XSI * All of the file descriptors, directory streams, conversion descriptors, and message catalog 10052 descriptorsopen in the calling process are closed. 10053 XSI XSI * If the parent process of the calling process is executing a wait( ),waitid( ),or waitpid ( ), and has | 10054 neither set its SA_NOCLDWAIT flag nor set SIGCHLD to SIG_IGN, it is notified of the 10055 calling process' termination and the low-order eight bits (that is, bits 0377) of status are made 10056 available to it. If the parent is not waiting, the child's status shall be made available to it 10057 XSI when the parent subsequently executes wait( ),waitid( ),or waitpid( ). | 10058 XSI XSI * If the parent process of the calling process is not executing a wait( ),waitid( ),or waitpid ( ), and | 10059 has not set its SA_NOCLDWAIT flag, or set SIGCHLD to SIG_IGN, the calling process is 10060 transformed into a zombie process. A zombie process is an inactive process and it shall be 10061 XSI deleted at some later time when its parent process executes wait( ),waitid( ),or waitpid( ). | 10062 * Termination of a process does not directly terminate its children. The sending of a SIGHUP 10063 signal as described below indirectly terminates children in some circumstances. 10064 * If the implementation supports the SIGCHLD signal, a SIGCHLD shall be sent to the parent 10065 process. System Interfaces, Issue 6 801 exit( ) System Interfaces 10066 XSI * If the parent process has set its SA_NOCLDWAIT flag, or set SIGCHLD to SIG_IGN, the 10067 status shall be discarded, and the lifetime of the calling process shall end immediately. If | 10068 SA_NOCLDWAIT is set, it is implementation-defined whether a SIGCHLD signal shall be | 10069 sent to the parent process. 10070 * The parent process ID of all of the calling process' existing child processes and zombie 10071 processes is set to the process ID of an implementation-defined system process. That is, these | 10072 processes are inherited by a special system process. | 10073 XSI * Each attached shared-memory segment is detached and the value of shm_nattch (see 10074 shmget( )) in the data structure associated with its shared memory ID is decremented by 1. 10075 XSI * For each semaphore for which the calling process has set a semadj value (see semop( )), that 10076 value is added to the semval of the specified semaphore. 10077 * If the process is a controlling process, the SIGHUP signal shall be sent to each process in the 10078 foreground process group of the controlling terminal belonging to the calling process. 10079 * If the process is a controlling process, the controlling terminal associated with the session is 10080 disassociated from the session, allowing it to be acquired by a new controlling process. 10081 * If the exit of the process causes a process group to become orphaned, and if any member of 10082 the newly-orphaned process group is stopped, then a SIGHUP signal followed by a 10083 SIGCONT signal shall be sent to each process in the newly-orphaned process group. 10084 SEM * All open named semaphores in the calling process shall be closed as if by appropriate calls to 10085 sem_close( ). 10086 ML * Any memory locks established by the process via calls to mlockall ( ) or mlock( ) shall be 10087 removed. If locked pages in the address space of the calling process are also mapped into the 10088 address spaces of other processes and are locked by those processes, the locks established by 10089 the other processes shall be unaffected by the call by this process to _Exit( ) or _exit( ). | 10090 MF|SHM * Memory mappings created in the process are unmapped before the process is destroyed. 10091 TYM * Any blocks of typed memory that were mapped in the calling process are unmapped, as if 10092 munmap( ) was implicitly called to unmap them. 10093 MSG * All open message queue descriptors in the calling process shall be closed as if by appropriate 10094 calls to mq_close( ). 10095 AIO * Any outstanding cancelable asynchronous I/O operations may be canceled. Those 10096 asynchronous I/O operations that are not canceled shall complete as if the _Exit( ) or _exit( ) | 10097 operation had not yet occurred, but any associated signal notifications shall be suppressed. 10098 The _Exit( ) or _exit( ) operation may block awaiting such I/O completion. Whether any I/O | 10099 is canceled, and which I/O may be canceled upon _Exit( ) or _exit( ), is implementation- | 10100 defined. | 10101 * Threads terminated by a call to _Exit( ) or _exit( ) shall not invoke their cancelation cleanup | 10102 handlers or per-thread data destructors. 10103 TRC If the calling process is a trace controller process, any trace streams that were created by the | 10104 calling process shall be shut down as described by the posix_trace_shutdown( ) function, and any | 10105 process' mapping of trace event names to trace event type identifiers built for these trace | 10106 streams may be deallocated. | 802 Technical Standard (2000) (Draft July 31, 2000) System Interfaces exit( ) 10107 RETURN VALUE 10108 These functions do not return. 10109 ERRORS 10110 No errors are defined. 10111 EXAMPLES 10112 None. 10113 APPLICATION USAGE 10114 Normally applications should use exit( ) rather than _Exit( ) or _exit( ). | 10115 RATIONALE 10116 Process Termination 10117 Early proposals drew a different distinction between normal and abnormal process termination. | 10118 Abnormal termination was caused only by certain signals and resulted in implementation- | 10119 defined ``actions'', as discussed below. Subsequent proposals distinguished three types of | 10120 termination: normal termination (as in the current specification), simple abnormal termination, and | 10121 abnormal termination with actions. Again the distinction between the two types of abnormal | 10122 termination was that they were caused by different signals and that implementation-defined | 10123 actions would result in the latter case. Given that these actions were completely | 10124 implementation-defined, the early proposals were only saying when the actions could occur and | 10125 how their occurrence could be detected, but not what they were. This was of little or no use to 10126 portable applications, and thus the distinction is not made in this volume of | 10127 IEEE Std. 1003.1-200x. | 10128 The implementation-defined actions usually include, in most historical implementations, the | 10129 creation of a file named core in the current working directory of the process. This file contains an 10130 image of the memory of the process, together with descriptive information about the process, 10131 perhaps sufficient to reconstruct the state of the process at the receipt of the signal. 10132 There is a potential security problem in creating a core file if the process was set-user-ID and the 10133 current user is not the owner of the program, if the process was set-group-ID and none of the 10134 user's groups match the group of the program, or if the user does not have permission to write in 10135 the current directory. In this situation, an implementation either should not create a core file or 10136 should make it unreadable by the user. 10137 Despite the silence of this volume of IEEE Std. 1003.1-200x on this feature, applications are 10138 advised not to create files named core because of potential conflicts in many implementations. 10139 Some historical implementations use a different name than core for the file, such as by 10140 appending the process ID to the file name. 10141 Terminating a Process 10142 It is important that the consequences of process termination as described occur regardless of 10143 whether the process called _exit( ) (perhaps indirectly through exit( )) or instead was terminated 10144 due to a signal or for some other reason. Note that in the specific case of exit( ) this means that 10145 the status argument to exit( ) is treated the same as the status argument to _exit( ). 10146 A language other than C may have other termination primitives than the C-language exit( ) 10147 function, and programs written in such a language should use its native termination primitives, 10148 but those should have as part of their function the behavior of _exit( ) as described. 10149 Implementations in languages other than C are outside the scope of the present version of this 10150 volume of IEEE Std. 1003.1-200x, however. System Interfaces, Issue 6 803 exit( ) System Interfaces 10151 As required by the ISO C standard, using return from main( ) is equivalent to calling exit( ) with 10152 the same argument value. Also, reaching the end of the main( ) function is equivalent to using 10153 exit( ) with an unspecified value. 10154 A value of zero (or EXIT_SUCCESS, which is required to be zero) for the argument status 10155 conventionally indicates successful termination. This corresponds to the specification for exit( ) 10156 in the ISO C standard. The convention is followed by utilities such as make and various shells, 10157 which interpret a zero status from a child process as success. For this reason, applications should 10158 not call exit(0) or _exit(0) when they terminate unsuccessfully; for example, in signal-catching 10159 functions. 10160 Historically, the implementation-defined process that inherits children whose parents have | 10161 terminated without waiting on them is called init and has a process ID of 1. 10162 The sending of a SIGHUP to the foreground process group when a controlling process 10163 terminates corresponds to somewhat different historical implementations. In System V, the 10164 kernel sends a SIGHUP on termination of (essentially) a controlling process. In 4.2 BSD, the 10165 kernel does not send SIGHUP in a case like this, but the termination of a controlling process is 10166 usually noticed by a system daemon, which arranges to send a SIGHUP to the foreground 10167 process group with the vhangup( ) function. However, in 4.2 BSD, due to the behavior of the 10168 shells that support job control, the controlling process is usually a shell with no other processes 10169 in its process group. Thus, a change to make _exit( ) behave this way in such systems should not 10170 cause problems with existing applications. 10171 The termination of a process may cause a process group to become orphaned in either of two 10172 ways. The connection of a process group to its parent(s) outside of the group depends on both 10173 the parents and their children. Thus, a process group may be orphaned by the termination of the 10174 last connecting parent process outside of the group or by the termination of the last direct 10175 descendant of the parent process(es). In either case, if the termination of a process causes a 10176 process group to become orphaned, processes within the group are disconnected from their job 10177 control shell, which no longer has any information on the existence of the process group. 10178 Stopped processes within the group would languish forever. In order to avoid this problem, 10179 newly orphaned process groups that contain stopped processes are sent a SIGHUP signal and a 10180 SIGCONT signal to indicate that they have been disconnected from their session. The SIGHUP 10181 signal causes the process group members to terminate unless they are catching or ignoring 10182 SIGHUP. Under most circumstances, all of the members of the process group are stopped if any 10183 of them are stopped. 10184 The action of sending a SIGHUP and a SIGCONT signal to members of a newly orphaned 10185 process group is similar to the action of 4.2 BSD, which sends SIGHUP and SIGCONT to each 10186 stopped child of an exiting process. If such children exit in response to the SIGHUP, any 10187 additional descendants receive similar treatment at that time. In this volume of 10188 IEEE Std. 1003.1-200x, the signals are sent to the entire process group at the same time. Also, in 10189 this volume of IEEE Std. 1003.1-200x, but not in 4.2 BSD, stopped processes may be orphaned, 10190 but may be members of a process group that is not orphaned; therefore, the action taken at 10191 _exit( ) must consider processes other than child processes. 10192 It is possible for a process group to be orphaned by a call to setpgid( ) or setsid( ), as well as by 10193 process termination. This volume of IEEE Std. 1003.1-200x does not require sending SIGHUP 10194 and SIGCONT in those cases, because, unlike process termination, those cases are not caused 10195 accidentally by applications that are unaware of job control. An implementation can choose to 10196 send SIGHUP and SIGCONT in those cases as an extension; such an extension must be 10197 documented as required in . | 10198 The ISO/IEC 9899: 1999 standard adds the _Exit( ) function that results in immediate program | 10199 termination without triggering signals or atexit( )-registered functions. In IEEE Std. 1003.1-200x, | 804 Technical Standard (2000) (Draft July 31, 2000) System Interfaces exit( ) 10200 this is equivalent to the _exit( ) function. | 10201 FUTURE DIRECTIONS 10202 None. 10203 SEE ALSO 10204 atexit( ), close( ), fclose( ), longjmp( ), (posix_trace_eventid), | 10205 posix_trace_shutdown( ), posix_trace_trid_eventid_open( ), semop( ), shmget( ), sigaction( ), wait( ), | 10206 waitid( ), waitpid( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , | 10207 CHANGE HISTORY 10208 First released in Issue 1. Derived from Issue 1 of the SVID. | 10209 Issue 4 10210 The header is added to the SYNOPSIS for _exit( ). 10211 In the DESCRIPTION, text is added describing the behavior when a function registered by 10212 atexit( ) fails to return, and the consequences of calling exit( ) more than once. 10213 The phrase ``If the implementation supports job control'' is removed from the last bullet in the 10214 DESCRIPTION. This is because job control is now defined as mandatory for all conforming 10215 implementations. 10216 The following change is incorporated for alignment with the ISO C standard: 10217 * In the DESCRIPTION, interactions between exit( ) and atexit( ) are defined, and it is now 10218 stated explicitly that all files created by tmpfile( ) are removed. 10219 Issue 4, Version 2 10220 The following changes to the DESCRIPTION are incorporated for X/OPEN UNIX conformance: 10221 * References to the functions wait3( ) and waitid( ) are added in appropriate places throughout 10222 the text. 10223 * Interactions with the SA_NOCLDWAIT flag and SIGCHLD signal are defined. 10224 * It is specified that each mapped memory object is unmapped. 10225 Issue 5 10226 The DESCRIPTION is updated for alignment with the POSIX Realtime Extension and the POSIX 10227 Threads Extension. 10228 Interactions with the SA_NOCLDWAIT flag and SIGCHLD signal are further clarified. 10229 The values of status from exit( ) are better described. 10230 Issue 6 10231 Extensions beyond the ISO C standard are now marked. 10232 The DESCRIPTION is updated for alignment with IEEE Std. 1003.1j-2000 by adding semantics 10233 for typed memory. | 10234 The following changes are made for alignment with the ISO/IEC 9899: 1999 standard: | 10235 * The _Exit( ) function is included. | 10236 * The DESCRIPTION is updated. | 10237 The description of tracing semantics is added for alignment with IEEE Std. 1003.1q-2000. | 10238 References to the wait3( ) function are removed. | System Interfaces, Issue 6 805 exp( ) System Interfaces 10239 NAME 10240 exp, expf, expl - exponential function | 10241 SYNOPSIS 10242 #include 10243 double exp(double x); 10244 float expf(float x); | 10245 long double expl(long double x); | 10246 DESCRIPTION | 10247 CX The functionality described on this reference page is aligned with the ISO C standard. Any 10248 conflict between the requirements described here and the ISO C standard is unintentional. This 10249 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 10250 These functions shall compute the exponent of x, defined as ex. | 10251 An application wishing to check for error situations should set errno to 0 before calling exp( ). If 10252 errno is non-zero on return, or the return value is NaN, an error has occurred. 10253 RETURN VALUE 10254 Upon successful completion, these functions shall return the exponential value of x. | 10255 If the correct value would cause overflow, exp( ) shall return HUGE_VAL and set errno to 10256 [ERANGE]. | 10257 If the correct value would cause underflow, exp( ) shall return 0 and may set errno to [ERANGE]. 10258 XSI If x is NaN, NaN shall be returned and errno may be set to [EDOM]. | 10259 ERRORS 10260 These functions shall fail if: | 10261 [ERANGE] The result overflows. | 10262 These functions may fail if: | 10263 XSI [EDOM] The value of x is NaN. | 10264 [ERANGE] The result underflows | 10265 XSI No other errors shall occur. 10266 EXAMPLES 10267 None. 10268 APPLICATION USAGE 10269 None. 10270 RATIONALE 10271 None. 10272 FUTURE DIRECTIONS 10273 None. 10274 SEE ALSO 10275 isnan( ), log( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 10276 CHANGE HISTORY 10277 First released in Issue 1. Derived from Issue 1 of the SVID. | 806 Technical Standard (2000) (Draft July 31, 2000) System Interfaces exp( ) 10278 Issue 4 10279 References to matherr( ) are removed. 10280 The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 10281 ISO C standard and to rationalize error handling in the mathematics functions. 10282 The return value specified for [EDOM] is marked as an extension. | 10283 Issue 5 10284 The DESCRIPTION is updated to indicate how an application should check for an error. This 10285 text was previously published in the APPLICATION USAGE section. | 10286 Issue 6 || 10287 The expf( ) and expl( ) functions are added for alignment with the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 807 exp2( ) System Interfaces 10288 NAME | 10289 exp2, exp2f, exp2l - exponential base 2 functions | 10290 SYNOPSIS | 10291 #include | 10292 double exp2(double x); | 10293 float exp2f(float x); | 10294 long double exp2l(long double x); | 10295 DESCRIPTION | 10296 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 10297 conflict between the requirements described here and the ISO C standard is unintentional. This | 10298 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 10299 These functions shall compute the base 2 exponent of x, defined as ex. | 10300 An application wishing to check for error situations should set errno to 0 before calling these | 10301 functions. If errno is non-zero on return, or the return value is NaN, an error has occurred. | 10302 RETURN VALUE | 10303 Upon successful completion, these functions shall return 2x. | 10304 If the correct value would cause overflow, these functions shall return HUGE_VAL and set errno | 10305 to [ERANGE]. | 10306 If the correct value would cause underflow, these functions shall return 0 and may set errno to | 10307 [ERANGE]. | 10308 If x is NaN, NaN shall be returned and errno may be set to [EDOM]. | 10309 ERRORS | 10310 These functions shall fail if: | 10311 [ERANGE] The result overflows. | 10312 These functions may fail if: | 10313 [EDOM] The value of x is NaN. | 10314 [ERANGE] The result underflows | 10315 No other errors shall occur. | 10316 EXAMPLES | 10317 None. | 10318 APPLICATION USAGE | 10319 None. | 10320 RATIONALE | 10321 None. | 10322 FUTURE DIRECTIONS | 10323 None. | 10324 SEE ALSO | 10325 exp( ), isnan( ), log( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 808 Technical Standard (2000) (Draft July 31, 2000) System Interfaces exp2( ) 10326 CHANGE HISTORY || 10327 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 809 expm1( ) System Interfaces 10328 NAME 10329 expm1, expm1f, expm1l - compute exponential functions | 10330 SYNOPSIS 10331 #include | 10332 double expm1(double x); | 10333 float expm1f(float x); | 10334 long double expm1l(long double x); | 10335 DESCRIPTION | 10336 These functions shall compute ex-1.0. | 10337 RETURN VALUE 10338 If x is NaN, then these functions shall return NaN and errno may be set to [EDOM]. | 10339 If x is positive infinity, these functions shall return positive infinity. | 10340 If x is negative infinity, these functions shall return -1.0. | 10341 If the value overflows, these functions shall return HUGE_VAL and may set errno to [ERANGE]. | 10342 ERRORS 10343 These functions may fail if: | 10344 [EDOM] The value of x is NaN. | 10345 [ERANGE] The result overflows. | 10346 EXAMPLES 10347 None. 10348 APPLICATION USAGE 10349 The value of expm1(x) may be more accurate than exp(x)-1.0 for small values of x. 10350 The expm1( ) and log1p( ) functions are useful for financial calculations of ((1+x)n-1)/x, namely: 10351 expm1(n * log1p(x))/x 10352 when x is very small (for example, when calculating small daily interest rates). These functions 10353 also simplify writing accurate inverse hyperbolic functions. 10354 RATIONALE 10355 None. 10356 FUTURE DIRECTIONS 10357 None. 10358 SEE ALSO 10359 exp( ), ilogb( ), log1p( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 10360 CHANGE HISTORY 10361 First released in Issue 4, Version 2. 10362 Issue 5 10363 Moved from X/OPEN UNIX extension to BASE. | 10364 Issue 6 | 10365 The expm1f( ) and expm1l( ) functions are added for alignment with the ISO/IEC 9899: 1999 | 10366 standard. | 810 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fabs( ) 10367 NAME 10368 fabs, fabsf, fabsl - absolute value function | 10369 SYNOPSIS 10370 #include 10371 double fabs(double x); 10372 float fabsf(float x); | 10373 long double fabsl(long double x); | 10374 DESCRIPTION | 10375 CX The functionality described on this reference page is aligned with the ISO C standard. Any 10376 conflict between the requirements described here and the ISO C standard is unintentional. This 10377 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 10378 These functions shall compute the absolute value of x,|x|. | 10379 An application wishing to check for error situations should set errno to 0 before calling fabs( ). If 10380 errno is non-zero on return, or the return value is NaN, an error has occurred. 10381 RETURN VALUE 10382 Upon successful completion, these functions shall return the absolute value of x. | 10383 XSI If x is NaN, NaN shall be returned and errno may be set to [EDOM]. | 10384 If the result underflows, 0 shall be returned and errno may be set to [ERANGE]. | 10385 ERRORS 10386 These functions may fail if: | 10387 XSI [EDOM] The value of x is NaN. | 10388 [ERANGE] The result underflows | 10389 XSI No other errors shall occur. 10390 EXAMPLES 10391 None. 10392 APPLICATION USAGE 10393 None. 10394 RATIONALE 10395 None. 10396 FUTURE DIRECTIONS 10397 None. 10398 SEE ALSO 10399 isnan( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 10400 CHANGE HISTORY 10401 First released in Issue 1. Derived from Issue 1 of the SVID. | 10402 Issue 4 10403 References to matherr( ) are removed. 10404 The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 10405 ISO C standard and to rationalize error handling in the mathematics functions. 10406 The return value specified for [EDOM] is marked as an extension. System Interfaces, Issue 6 811 fabs( ) System Interfaces 10407 Issue 5 10408 The DESCRIPTION is updated to indicate how an application should check for an error. This 10409 text was previously published in the APPLICATION USAGE section. | 10410 Issue 6 | 10411 The fabsf( ) and fabsl( ) functions are added for alignment with the ISO/IEC 9899: 1999 standard. | 812 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fattach( ) 10412 NAME 10413 fattach - attach a STREAMS-based file descriptor to a file in the file system name space 10414 (STREAMS) 10415 SYNOPSIS 10416 XSR #include 10417 int fattach(int fildes, const char *path); 10418 10419 DESCRIPTION 10420 Notes to Reviewers 10421 This section with side shading will not appear in the final copy. - Ed. 10422 Re D1, XSH, ERN 111: if the original file had multiple links, the streams file still has only one? I 10423 presume that a stream is actually attached to an inode, not a file name. If so, there continue to 10424 exist multiple links to the object, even though it shows a link count of 1. If it associated the 10425 stream with a file name, then the following sentence is wrong. 10426 The fattach( ) function attaches a STREAMS-based file descriptor to a file, effectively associating 10427 a path name with fildes. The application shall ensure that the fildes argument is a valid open file 10428 descriptor associated with a STREAMS file. The path argument points to a path name of an 10429 existing file. The application shall ensure that the process has appropriate privileges, or is the 10430 owner of the file named by path and has write permission. A successful call to fattach( ) shall 10431 cause all path names that name the file named by path to name the STREAMS file associated 10432 with fildes, until the STREAMS file is detached from the file. A STREAMS file can be attached to 10433 more than one file and can have several path names associated with it. 10434 The attributes of the named STREAMS file shall be initialized as follows: the permissions, user 10435 ID, group ID, and times are set to those of the file named by path, the number of links is set to 1, 10436 and the size and device identifier are set to those of the STREAMS file associated with fildes. If 10437 any attributes of the named STREAMS file are subsequently changed (for example, by chmod( )), 10438 neither the attributes of the underlying file nor the attributes of the STREAMS file to which fildes 10439 refers shall be affected. 10440 File descriptors referring to the underlying file, opened prior to an fattach( ) call, shall continue to 10441 refer to the underlying file. 10442 RETURN VALUE 10443 Upon successful completion, fattach( ) shall return 0. Otherwise, -1 shall be returned and errno 10444 set to indicate the error. 10445 ERRORS 10446 The fattach( ) function shall fail if: 10447 [EACCES] Search permission is denied for a component of the path prefix, or the process | 10448 is the owner of path but does not have write permissions on the file named by 10449 path. 10450 [EBADF] The fildes argument is not a valid open file descriptor. | 10451 [EBUSY] The file named by path is currently a mount point or has a STREAMS file | 10452 attached to it. | 10453 [ELOOP] A loop exists in symbolic links encountered during resolution of the path | 10454 argument. | System Interfaces, Issue 6 813 fattach( ) System Interfaces 10455 [ENAMETOOLONG] | 10456 The size of path exceeds {PATH_MAX} or a component of path is longer than | 10457 {NAME_MAX}. | 10458 [ENOENT] A component of path does not name an existing file or path is an empty string. | 10459 [ENOTDIR] A component of the path prefix is not a directory. | 10460 [EPERM] The effective user ID of the process is not the owner of the file named by path | 10461 and the process does not have appropriate privilege. | 10462 The fattach( ) function may fail if: 10463 [EINVAL] The fildes argument does not refer to a STREAMS file. | 10464 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during | 10465 resolution of the path argument. | 10466 [ENAMETOOLONG] | 10467 Path name resolution of a symbolic link produced an intermediate result 10468 whose length exceeds {PATH_MAX}. 10469 [EXDEV] A link to a file on another file system was attempted. | 10470 EXAMPLES 10471 Attaching a File Descriptor to a File 10472 In the following example, fd refers to an open STREAMS file. The call to fattach( ) associates this 10473 STREAM with the file /tmp/named-STREAM, such that any future calls to open /tmp/named- 10474 STREAM, prior to breaking the attachment via a call to fdetach( ), will instead create a new file 10475 handle referring to the STREAMS file associated with fd. 10476 #include 10477 ... 10478 int fd; 10479 char *filename = "/tmp/named-STREAM"; 10480 int ret; 10481 ret = fattach(fd, filename); 10482 APPLICATION USAGE 10483 The fattach( ) function behaves similarly to the traditional mount( ) function in the way a file is 10484 temporarily replaced by the root directory of the mounted file system. In the case of fattach( ), the 10485 replaced file need not be a directory and the replacing file is a STREAMS file. 10486 RATIONALE 10487 None. 10488 FUTURE DIRECTIONS 10489 None. 10490 SEE ALSO 10491 fdetach( ), isastream( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 10492 CHANGE HISTORY 10493 First released in Issue 4, Version 2. 814 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fattach( ) 10494 Issue 5 10495 Moved from X/OPEN UNIX extension to BASE. 10496 The [EXDEV] error is added to the list of optional errors in the ERRORS section. 10497 Issue 6 10498 This function is marked as part of the XSI STREAMS Option Group. 10499 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. | 10500 The wording of the mandatory [ELOOP] error condition is updated, and a second optional | 10501 [ELOOP] error condition is added. | System Interfaces, Issue 6 815 fchdir( ) System Interfaces 10502 NAME 10503 fchdir - change working directory | 10504 SYNOPSIS 10505 XSI #include 10506 int fchdir(int fildes); 10507 10508 DESCRIPTION 10509 The fchdir( ) function has the same effect as chdir( ) except that the directory that is to be the new 10510 current working directory is specified by the file descriptor fildes. 10511 RETURN VALUE 10512 Upon successful completion, fchdir( ) shall return 0. Otherwise, it shall return -1 and set errno to 10513 indicate the error. On failure the current working directory shall remain unchanged. 10514 ERRORS 10515 The fchdir( ) function shall fail if: 10516 [EACCES] Search permission is denied for the directory referenced by fildes. | 10517 [EBADF] The fildes argument is not an open file descriptor. | 10518 [ENOTDIR] The open file descriptor fildes does not refer to a directory. | 10519 The fchdir( ) may fail if: 10520 [EINTR] A signal was caught during the execution of fchdir( ). | 10521 [EIO] An I/O error occurred while reading from or writing to the file system. | 10522 EXAMPLES 10523 None. 10524 APPLICATION USAGE 10525 None. 10526 RATIONALE 10527 None. 10528 FUTURE DIRECTIONS 10529 None. 10530 SEE ALSO 10531 chdir( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 10532 CHANGE HISTORY 10533 First released in Issue 4, Version 2. 10534 Issue 5 10535 Moved from X/OPEN UNIX extension to BASE. 816 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fchmod( ) 10536 NAME 10537 fchmod - change mode of a file 10538 SYNOPSIS 10539 #include 10540 int fchmod(int fildes, mode_t mode); 10541 DESCRIPTION 10542 The fchmod( ) function has the same effect as chmod( ) except that the file whose permissions are 10543 changed is specified by the file descriptor fildes. 10544 SHM If fildes references a shared memory object, the fchmod( ) function need only affect the S_IRUSR, 10545 S_IWUSR, S_IRGRP, S_IWGRP, S_IROTH, and S_IWOTH file permission bits. 10546 TYM If fildes references a typed memory object, the behavior of fchmod( ) is unspecified. | 10547 Notes to Reviewers | 10548 This section with side shading will not appear in the final copy. - Ed. | 10549 D3, XSH, ERN 178 suggests adding text as follows: "If fildes refers to a STREAM (which is | 10550 fattached() into the file system name space) the call returns successfully, doing nothing. If fildes | 10551 refers to a stream, ." | 10552 RETURN VALUE | 10553 Upon successful completion, fchmod( ) shall return 0. Otherwise, it shall return -1 and set errno to 10554 indicate the error. 10555 ERRORS 10556 The fchmod( ) function shall fail if: 10557 [EBADF] The fildes argument is not an open file descriptor. | 10558 [EPERM] The effective user ID does not match the owner of the file and the process | 10559 does not have appropriate privilege. 10560 [EROFS] The file referred to by fildes resides on a read-only file system. | 10561 The fchmod( ) function may fail if: 10562 XSI [EINTR] The fchmod( ) function was interrupted by a signal. | 10563 XSI [EINVAL] The value of the mode argument is invalid. | 10564 [EINVAL] The fildes argument refers to a pipe and the implementation disallows 10565 execution of fchmod( ) on a pipe. 10566 EXAMPLES 10567 Changing the Current Permissions for a File 10568 The following example shows how to change the permissions for a file named /home/cnd/mod1 10569 so that the owner and group have read/write/execute permissions, but the world only has 10570 read/write permissions. 10571 #include 10572 #include 10573 mode_t mode; 10574 int fildes; 10575 ... System Interfaces, Issue 6 817 fchmod( ) System Interfaces 10576 fildes = open("/home/cnd/mod1", O_RDWR); 10577 fchmod(fildes, S_IRWXU | S_IRWXG | S_IROTH | S_IWOTH); 10578 APPLICATION USAGE 10579 None. 10580 RATIONALE 10581 None. 10582 FUTURE DIRECTIONS 10583 None. 10584 SEE ALSO 10585 chmod( ), chown( ), creat( ), fcntl( ), fstatvfs( ), mknod( ), open( ), read( ), stat( ), write( ), the Base | 10586 Definitions volume of IEEE Std. 1003.1-200x, | 10587 CHANGE HISTORY 10588 First released in Issue 4, Version 2. 10589 Issue 5 10590 Moved from X/OPEN UNIX extension to BASE and aligned with fchmod( ) in the POSIX 10591 Realtime Extension. Specifically, the second paragraph of the DESCRIPTION is added and a 10592 second instance of [EINVAL] is defined in the list of optional errors. 10593 Issue 6 10594 The DESCRIPTION is updated for alignment with IEEE Std. 1003.1j-2000 by stating that 10595 fchmod( ) behavior is unspecified for typed memory objects. 818 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fchown( ) 10596 NAME 10597 fchown - change owner and group of a file | 10598 SYNOPSIS 10599 #include | 10600 int fchown(int fildes, uid_t owner, gid_t group); 10601 DESCRIPTION | 10602 The fchown( ) function has the same effect as chown( ) except that the file whose owner and group 10603 are changed is specified by the file descriptor fildes. 10604 RETURN VALUE 10605 Upon successful completion, fchown( ) shall return 0. Otherwise, it shall return -1 and set errno to 10606 indicate the error. 10607 ERRORS 10608 The fchown( ) function shall fail if: 10609 [EBADF] The fildes argument is not an open file descriptor. | 10610 [EPERM] The effective user ID does not match the owner of the file or the process does | 10611 not have appropriate privilege and _POSIX_CHOWN_RESTRICTED indicates 10612 that such privilege is required. 10613 [EROFS] The file referred to by fildes resides on a read-only file system. | 10614 The fchown( ) function may fail if: 10615 [EINVAL] The owner or group ID is not a value supported by the implementation. The | 10616 fildes argument refers to a pipe and the implementation disallows execution of 10617 fchown( ) on a pipe. | 10618 Notes to Reviewers | 10619 This section with side shading will not appear in the final copy. - Ed. | 10620 D3, XSH, ERN 177 states that STREAMS ignore the call, but raises a question | 10621 about AF_UNIX sockets in the file system name space. | 10622 [EIO] A physical I/O error has occurred. | 10623 [EINTR] The fchown( ) function was interrupted by a signal which was caught. | 10624 EXAMPLES 10625 Changing the Current Owner of a File 10626 The following example shows how to change the owner of a file named /home/cnd/mod1 to 10627 ``jones'' and the group to ``cnd''. 10628 The numeric value for the user ID is obtained by extracting the user ID from the user database 10629 entry associated with ``jones''. Similarly, the numeric value for the group ID is obtained by 10630 extracting the group ID from the group database entry associated with ``cnd''. This example 10631 assumes the calling program has appropriate privileges. 10632 #include 10633 #include 10634 #include 10635 #include 10636 #include System Interfaces, Issue 6 819 fchown( ) System Interfaces 10637 struct passwd *pwd; 10638 struct group *grp; 10639 int fildes; 10640 ... 10641 fildes = open("/home/cnd/mod1", O_RDWR); 10642 pwd = getpwnam("jones"); 10643 grp = getgrnam("cnd"); 10644 fchown(fildes, pwd->pw_uid, grp->gr_gid); 10645 APPLICATION USAGE 10646 None. 10647 RATIONALE 10648 None. 10649 FUTURE DIRECTIONS 10650 None. 10651 SEE ALSO 10652 chown( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 10653 CHANGE HISTORY 10654 First released in Issue 4, Version 2. 10655 Issue 5 10656 Moved from X/OPEN UNIX extension to BASE. 10657 Issue 6 10658 The following changes were made to align with the IEEE P1003.1a draft standard: 10659 * Clarification is added that a call to fchown( ) may not be allowed on a pipe. 10660 The fchwon( ) function is now defined as mandatory. | 820 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fclose( ) 10661 NAME 10662 fclose - close a stream 10663 SYNOPSIS 10664 #include 10665 int fclose(FILE *stream); 10666 DESCRIPTION 10667 CX The functionality described on this reference page is aligned with the ISO C standard. Any 10668 conflict between the requirements described here and the ISO C standard is unintentional. This 10669 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 10670 The fclose( ) function shall cause the stream pointed to by stream to be flushed and the associated 10671 file to be closed. Any unwritten buffered data for the stream shall be written to the file; any 10672 unread buffered data shall be discarded. Whether or not the call succeeds, the stream shall be | 10673 disassociated from the file and any buffer set by the setbuf( ) or setvbuf( ) function shall be | 10674 disassociated from the stream. If the associated buffer was automatically allocated, it shall be | 10675 CX deallocated. It shall mark for update the st_ctime and st_mtime fields of the underlying file, if the | 10676 stream was writable, and if buffered data remains that has not yet been written to the file. The 10677 fclose( ) function shall perform the equivalent of a close( ) on the file descriptor that is associated | 10678 with the stream pointed to by stream. 10679 After the call to fclose( ), any use of stream results in undefined behavior. | 10680 RETURN VALUE 10681 CX Upon successful completion, fclose( ) shall return 0; otherwise, it shall return EOF and set errno to 10682 indicate the error. 10683 ERRORS 10684 The fclose( ) function shall fail if: 10685 CX [EAGAIN] The O_NONBLOCK flag is set for the file descriptor underlying stream and the | 10686 process would be delayed in the write operation. 10687 CX [EBADF] The file descriptor underlying stream is not valid. | 10688 CX [EFBIG] An attempt was made to write a file that exceeds the maximum file size. | 10689 XSI [EFBIG] An attempt was made to write a file that exceeds the process' file size limit. | 10690 CX [EFBIG] The file is a regular file and an attempt was made to write at or beyond the | 10691 offset maximum associated with the corresponding stream. 10692 CX [EINTR] The fclose( ) function was interrupted by a signal. | 10693 CX [EIO] The process is a member of a background process group attempting to write | 10694 to its controlling terminal, TOSTOP is set, the process is neither ignoring nor 10695 blocking SIGTTOU, and the process group of the process is orphaned. This 10696 error may also be returned under implementation-defined conditions. | 10697 CX [ENOSPC] There was no free space remaining on the device containing the file. | 10698 CX [EPIPE] An attempt is made to write to a pipe or FIFO that is not open for reading by | 10699 any process. A SIGPIPE signal shall also be sent to the thread. 10700 The fclose( ) function may fail if: 10701 CX [ENXIO] A request was made of a nonexistent device, or the request was outside the | 10702 capabilities of the device. System Interfaces, Issue 6 821 fclose( ) System Interfaces 10703 EXAMPLES 10704 None. 10705 APPLICATION USAGE 10706 None. 10707 RATIONALE 10708 None. 10709 FUTURE DIRECTIONS 10710 None. 10711 SEE ALSO 10712 close( ), fopen( ), getrlimit( ), ulimit( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 10713 10714 CHANGE HISTORY 10715 First released in Issue 1. Derived from Issue 1 of the SVID. | 10716 Issue 4 10717 The last sentence of the first paragraph in the DESCRIPTION is changed to say close( ) instead of 10718 fclose( ). This was an error in Issue 3. 10719 The following paragraph is withdrawn from the DESCRIPTION (by POSIX as well as X/Open) 10720 because of the possibility of causing applications to malfunction, and the impossibility of 10721 implementing these mechanisms for pipes: 10722 If the file is not already at EOF, and the file is one capable of seeking, the file offset of the 10723 underlying open file description is adjusted so that the next operation on the open file 10724 description deals with the byte after the last one read from or written to the stream being 10725 closed. 10726 It is replaced with a statement that any subsequent use of stream is undefined. 10727 The [EFBIG] error is marked to indicate the extensions. 10728 Issue 4, Version 2 10729 A cross-reference to getrlimit( ) is added. 10730 Issue 5 10731 Large File Summit extensions are added. 10732 Issue 6 10733 Extensions beyond the ISO C standard are now marked. 10734 The following new requirements on POSIX implementations derive from alignment with the 10735 Single UNIX Specification: 10736 * The [EFBIG] error is added as part of the large file support extensions. 10737 * The [ENXIO] optional error condition is added. 10738 The DESCRIPTION is updated to note that the stream and any buffer are disassociated whether | 10739 or not the call succeeds. This is for alignment with the ISO/IEC 9899: 1999 standard. | 822 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fcntl( ) 10740 NAME 10741 fcntl - file control 10742 SYNOPSIS 10743 OH #include 10744 #include 10745 int fcntl(int fildes, int cmd, ...); 10746 DESCRIPTION 10747 The fcntl( ) function provides for control over open files. The fildes argument is a file descriptor. 10748 The available values for cmd are defined in , which include: 10749 F_DUPFD Return a new file descriptor which is the lowest numbered available (that is, 10750 not already open) file descriptor greater than or equal to the third argument, 10751 arg, taken as an integer of type int. The new file descriptor refers to the same 10752 open file description as the original file descriptor, and shares any locks. The 10753 FD_CLOEXEC flag associated with the new file descriptor is cleared to keep 10754 the file open across calls to one of the exec functions. 10755 F_GETFD Get the file descriptor flags defined in that are associated with the 10756 file descriptor fildes. File descriptor flags are associated with a single file 10757 descriptor and do not affect other file descriptors that refer to the same file. 10758 F_SETFD Set the file descriptor flags defined in , that are associated with fildes, 10759 to the third argument, arg, taken as type int. If the FD_CLOEXEC flag in the 10760 third argument is 0, the file shall remain open across the exec functions; 10761 otherwise, the file shall be closed upon successful execution of one of the exec 10762 functions. 10763 F_GETFL Get the file status flags and file access modes, defined in , for the file 10764 description associated with fildes. The file access modes can be extracted from 10765 the return value using the mask O_ACCMODE, which is defined in . 10766 File status flags and file access modes are associated with the file description 10767 and do not affect other file descriptors that refer to the same file with different 10768 open file descriptions. 10769 F_SETFL Set the file status flags, defined in , for the file description associated 10770 with fildes from the corresponding bits in the third argument, arg, taken as 10771 type int. Bits corresponding to the file access mode and the oflag values that 10772 are set in arg are ignored. If any bits in arg other than those mentioned here are 10773 changed by the application, the result is unspecified. 10774 F_GETOWN If fildes refers to a socket, get the process or process group ID specified to 10775 receive SIGURG signals when out-of-band data is available. Positive values 10776 indicate a process ID; negative values, other than -1, indicate a process group 10777 ID. If fildes does not refer to a socket, the results are unspecified. 10778 F_SETOWN If fildes refers to a socket, set the process or process group ID specified to 10779 receive SIGURG signals when out-of-band data is available, using the value of 10780 the third argument, arg, taken as type int. Positive values indicate a process 10781 ID; negative values, other than -1, indicate a process group ID. If fildes does 10782 not refer to a socket, the results are unspecified. 10783 The following values for cmd are available for advisory record locking. Record locking is 10784 supported for regular files, and may be supported for other files. System Interfaces, Issue 6 823 fcntl( ) System Interfaces 10785 F_GETLK Get the first lock which blocks the lock description pointed to by the third 10786 argument, arg, taken as a pointer to type struct flock, defined in . 10787 The information retrieved overwrites the information passed to fcntl( ) in the 10788 structure flock. If no lock is found that would prevent this lock from being 10789 created, then the structure shall be left unchanged except for the lock type 10790 which shall be set to F_UNLCK. 10791 F_SETLK Set or clear a file segment lock according to the lock description pointed to by 10792 the third argument, arg, taken as a pointer to type struct flock, defined in 10793 . F_SETLK is used to establish shared (or read) locks (F_RDLCK) or 10794 exclusive (or write) locks (F_WRLCK), as well as to remove either type of lock 10795 (F_UNLCK). F_RDLCK, F_WRLCK, and F_UNLCK are defined in . 10796 If a shared or exclusive lock cannot be set, fcntl( ) shall return immediately 10797 with a return value of -1. 10798 F_SETLKW This command is the same as F_SETLK except that if a shared or exclusive 10799 lock is blocked by other locks, the thread shall wait until the request can be 10800 satisfied. If a signal that is to be caught is received while fcntl( ) is waiting for a 10801 region, fcntl( ) shall be interrupted. Upon return from the signal handler, 10802 fcntl( ) shall return -1 with errno set to [EINTR], and the lock operation shall | 10803 not be done. 10804 Additional implementation-defined values for cmd may be defined in . Their names | 10805 shall start with F_. 10806 When a shared lock is set on a segment of a file, other processes shall be able to set shared locks 10807 on that segment or a portion of it. A shared lock prevents any other process from setting an 10808 exclusive lock on any portion of the protected area. A request for a shared lock shall fail if the 10809 file descriptor was not opened with read access. 10810 An exclusive lock shall prevent any other process from setting a shared lock or an exclusive lock 10811 on any portion of the protected area. A request for an exclusive lock shall fail if the file 10812 descriptor was not opened with write access. 10813 The structure flock describes the type (l_type), starting offset (l_whence), relative offset (l_start), 10814 size (l_len), and process ID (l_pid) of the segment of the file to be affected. 10815 The value of l_whence is {SEEK_SET}, {SEEK_CUR}, or {SEEK_END}, to indicate that the relative 10816 offset l_start bytes shall be measured from the start of the file, current position, or end of the file, 10817 respectively. The value of l_len is the number of consecutive bytes to be locked. The value of | 10818 l_len may be negative (where the definition of off_t permits negative values of l_len). The l_pid | 10819 field is only used with F_GETLK to return the process ID of the process holding a blocking lock. 10820 After a successful F_GETLK request, when a blocking lock is found, the values returned in the 10821 flock structure shall be as follows: 10822 l_type Type of blocking lock found. 10823 l_whence {SEEK_SET}. 10824 l_start Start of the blocking lock. 10825 l_len Length of the blocking lock. 10826 l_pid Process ID of the process that holds the blocking lock. 10827 If the command is F_SETLKW and the process must wait for another process to release a lock, 10828 then the range of bytes to be locked shall be determined before the fcntl( ) function blocks. If the 10829 file size or file descriptor seek offset change while fcntl( ) is blocked, this shall not affect the 10830 range of bytes locked. 824 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fcntl( ) 10831 If l_len is positive, the area affected starts at l_start and ends at l_start+ l_len-1. If l_len is | 10832 negative, the area affected starts at l_start+ l_len and ends at l_start-1. Locks may start and | 10833 extend beyond the current end of a file, but the application shall ensure that they are not 10834 negative relative to the beginning of the file. A lock shall be set to extend to the largest possible 10835 value of the file offset for that file by setting l_len to 0. If such a lock also has l_start set to 0 and 10836 l_whence is set to {SEEK_SET}, the whole file shall be locked. 10837 There shall be at most one type of lock set for each byte in the file. Before a successful return 10838 from an F_SETLK or an F_SETLKW request when the calling process has previously existing 10839 locks on bytes in the region specified by the request, the previous lock type for each byte in the 10840 specified region shall be replaced by the new lock type. As specified above under the 10841 descriptions of shared locks and exclusive locks, an F_SETLK or an F_SETLKW request 10842 (respectively) shall fail or block when another process has existing locks on bytes in the specified 10843 region and the type of any of those locks conflicts with the type specified in the request. 10844 All locks associated with a file for a given process shall be removed when a file descriptor for 10845 that file is closed by that process or the process holding that file descriptor terminates. Locks are 10846 not inherited by a child process. 10847 A potential for deadlock occurs if a process controlling a locked region is put to sleep by 10848 attempting to lock another process' locked region. If the system detects that sleeping until a 10849 locked region is unlocked would cause a deadlock, fcntl( ) shall fail with an [EDEADLK] error. | 10850 SHM When the file descriptor fildes refers to a shared memory object, the behavior of fcntl( ) shall be 10851 the same as for a regular file except the effect of the following values for the argument cmd shall 10852 be unspecified: F_SETFL, F_GETLK, F_SETLK, and F_SETLKW. 10853 TYM If fildes refers to a typed memory object, the result of the fcntl( ) function is unspecified. 10854 An unlock (F_UNLCK) request in which l_len is non-zero and the offset of the last byte of the | 10855 requested segment is the maximum value for an object of type off_t, when the process has an 10856 existing lock in which l_len is 0 and which includes the last byte of the requested segment, shall 10857 be treated as a request to unlock from the start of the requested segment with an l_len equal to 0. 10858 Otherwise, an unlock (F_UNLCK) request shall attempt to unlock only the requested segment. | 10859 RETURN VALUE 10860 Upon successful completion, the value returned shall depend on cmd as follows: 10861 F_DUPFD A new file descriptor. 10862 F_GETFD Value of flags defined in . The return value shall not be negative. 10863 F_SETFD Value other than -1. 10864 F_GETFL Value of file status flags and access modes. The return value is not negative. 10865 F_SETFL Value other than -1. 10866 F_GETLK Value other than -1. 10867 F_SETLK Value other than -1. 10868 F_SETLKW Value other than -1. 10869 F_GETOWN Value of the socket owner process or process group; this will not be -1. 10870 F_SETOWN Value other than -1. 10871 Otherwise, -1 shall be returned and errno set to indicate the error. System Interfaces, Issue 6 825 fcntl( ) System Interfaces 10872 ERRORS 10873 The fcntl( ) function shall fail if: 10874 [EACCES] or [EAGAIN] | 10875 The cmd argument is F_SETLK; the type of lock (l_type) is a shared (F_RDLCK) 10876 or exclusive (F_WRLCK) lock and the segment of a file to be locked is already 10877 exclusive-locked by another process, or the type is an exclusive lock and some 10878 portion of the segment of a file to be locked is already shared-locked or 10879 exclusive-locked by another process. 10880 [EBADF] The fildes argument is not a valid open file descriptor, or the argument cmd is | 10881 F_SETLK or F_SETLKW, the type of lock, l_type, is a shared lock (F_RDLCK), 10882 and fildes is not a valid file descriptor open for reading, or the type of lock 10883 l_type, is an exclusive lock (F_WRLCK), and fildes is not a valid file descriptor 10884 open for writing. 10885 [EINTR] The cmd argument is F_SETLKW and the function was interrupted by a signal. | 10886 [EINVAL] The cmd argument is invalid, or the cmd argument is F_DUPFD and arg is | 10887 negative or greater than or equal to {OPEN_MAX}, or the cmd argument is 10888 F_GETLK, F_SETLK, or F_SETLKW and the data pointed to by arg is not valid, 10889 or fildes refers to a file that does not support locking. 10890 [EMFILE] The argument cmd is F_DUPFD and {OPEN_MAX} file descriptors are | 10891 currently open in the calling process, or no file descriptors greater than or 10892 equal to arg are available. 10893 [ENOLCK] The argument cmd is F_SETLK or F_SETLKW and satisfying the lock or unlock | 10894 request would result in the number of locked regions in the system exceeding 10895 a system-imposed limit. | 10896 [EOVERFLOW] One of the values to be returned cannot be represented correctly. | 10897 [EOVERFLOW] The cmd argument is F_GETLK, F_SETLK, or F_SETLKW and the smallest or, | 10898 if l_len is non-zero, the largest offset of any byte in the requested segment 10899 cannot be represented correctly in an object of type off_t. | 10900 The fcntl( ) function may fail if: 10901 [EDEADLK] The cmd argument is F_SETLKW, the lock is blocked by some lock from | 10902 another process and putting the calling process to sleep, waiting for that lock 10903 to become free would cause a deadlock. 10904 EXAMPLES 10905 None. 10906 APPLICATION USAGE 10907 None. 10908 RATIONALE 10909 The ellipsis in the SYNOPSIS is the syntax specified by the ISO C standard for a variable number 10910 of arguments. It is used because System V uses pointers for the implementation of file locking 10911 functions. 10912 The arg values to F_GETFD, F_SETFD, F_GETFL, and F_SETFL all represent flag values to allow 10913 for future growth. Applications using these functions should do a read-modify-write operation 10914 on them, rather than assuming that only the values defined by this volume of 10915 IEEE Std. 1003.1-200x are valid. It is a common error to forget this, particularly in the case of 10916 F_SETFD. 826 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fcntl( ) 10917 This volume of IEEE Std. 1003.1-200x permits concurrent read and write access to file data using 10918 the fcntl( ) function; this is a change from the 1984 /usr/group standard and early proposals. 10919 Without concurrency controls, this feature may not be fully utilized without occasional loss of | 10920 data. | 10921 Data losses occur in several ways. One case occurs when several processes try to update the 10922 same record, without sequencing controls; several updates may occur in parallel and the last 10923 writer ``wins''. Another case is a bit-tree or other internal list-based database that is undergoing 10924 reorganization. Without exclusive use to the tree segment by the updating process, other reading 10925 processes chance getting lost in the database when the index blocks are split, condensed, 10926 inserted, or deleted. While fcntl( ) is useful for many applications, it is not intended to be overly 10927 general and does not handle the bit-tree example well. 10928 This facility is only required for regular files because it is not appropriate for many devices such 10929 as terminals and network connections. 10930 Since fcntl( ) works with ``any file descriptor associated with that file, however it is obtained'', 10931 the file descriptor may have been inherited through a fork( ) or exec operation and thus may 10932 affect a file that another process also has open. 10933 The use of the open file description to identify what to lock requires extra calls and presents 10934 problems if several processes are sharing an open file description, but there are too many 10935 implementations of the existing mechanism for this volume of IEEE Std. 1003.1-200x to use 10936 different specifications. 10937 Another consequence of this model is that closing any file descriptor for a given file (whether or 10938 not it is the same open file description that created the lock) causes the locks on that file to be 10939 relinquished for that process. Equivalently, any close for any file/process pair relinquishes the 10940 locks owned on that file for that process. But note that while an open file description may be 10941 shared through fork( ), locks are not inherited through fork( ). Yet locks may be inherited through 10942 one of the exec functions. 10943 The identification of a machine in a network environment is outside of the scope of this volume 10944 of IEEE Std. 1003.1-200x. Thus, an l_sysid member, such as found in System V, is not included in 10945 the locking structure. 10946 Before successful return from an F_SETLK or F_SETLKW request, the previous lock type for 10947 each byte in the specified region shall be replaced by the new lock type. This can result in a 10948 previously locked region being split into smaller regions. If this would cause the number of 10949 regions being held by all processes in the system to exceed a system-imposed limit, the fcntl( ) 10950 function shall return -1 with errno set to [ENOLCK]. | 10951 Mandatory locking was a major feature of the 1984 /usr/group standard. | 10952 For advisory file record locking to be effective, all processes that have access to a file must | 10953 cooperate and use the advisory mechanism before doing I/O on the file. Enforcement-mode | 10954 record locking is important when it cannot be assumed that all processes are cooperating. For | 10955 example, if one user uses an editor to update a file at the same time that a second user executes | 10956 another process that updates the same file and if only one of the two processes is using advisory | 10957 locking, the processes are not cooperating. Enforcement-mode record locking would protect | 10958 against accidental collisions. | 10959 Secondly, advisory record locking requires a process using locking to bracket each I/O operation | 10960 with lock (or test) and unlock operations. With enforcement-mode file and record locking, a 10961 process can lock the file once and unlock when all I/O operations have been completed. 10962 Enforcement-mode record locking provides a base that can be enhanced; for example, with 10963 sharable locks. That is, the mechanism could be enhanced to allow a process to lock a file so System Interfaces, Issue 6 827 fcntl( ) System Interfaces 10964 other processes could read it, but none of them could write it. 10965 Mandatory locks were omitted for several reasons: 10966 1. Mandatory lock setting was done by multiplexing the set-group-ID bit in most 10967 implementations; this was confusing, at best. 10968 2. The relationship to file truncation as supported in 4.2 BSD was not well specified. 10969 3. Any publicly readable file could be locked by anyone. Many historical implementations 10970 keep the password database in a publicly readable file. A malicious user could thus 10971 prohibit logins. Another possibility would be to hold open a long-distance telephone line. 10972 4. Some demand-paged historical implementations offer memory mapped files, and 10973 enforcement cannot be done on that type of file. 10974 Since sleeping on a region is interrupted with any signal, alarm( ) may be used to provide a 10975 timeout facility in applications requiring it. This is useful in deadlock detection. Because 10976 implementation of full deadlock detection is not always feasible, the [EDEADLK] error was | 10977 made optional. 10978 FUTURE DIRECTIONS 10979 None. 10980 SEE ALSO 10981 close( ), exec, open( ), sigaction( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , | 10982 , 10983 CHANGE HISTORY 10984 First released in Issue 1. Derived from Issue 1 of the SVID. | 10985 Issue 4 10986 The and headers are now marked as optional (OH); these headers do 10987 not need to be included on XSI-conformant systems. 10988 In the DESCRIPTION, sentences describing behavior when l_len is negative are marked as an 10989 extension, and the description of locks is corrected to make it a requirement on the application. 10990 The following change is incorporated for alignment with the ISO POSIX-1 standard: 10991 * In the DESCRIPTION, the meaning of a successful F_SETLK or F_SETLKW request is 10992 clarified, after a POSIX Request for Interpretation. 10993 Issue 5 10994 The DESCRIPTION is updated for alignment with the POSIX Realtime Extension and the POSIX 10995 Threads Extension. 10996 Large File Summit extensions are added. 10997 Issue 6 10998 In the SYNOPSIS, the inclusion of is no longer required. 10999 The following new requirements on POSIX implementations derive from alignment with the 11000 Single UNIX Specification: 11001 * The requirement to include has been removed. Although was 11002 required for conforming implementations of previous POSIX specifications, it was not 11003 required for UNIX applications. 11004 * In the DESCRIPTION, sentences describing behavior when l_len is negative are now 11005 mandated, and the description of unlock (F_UNLOCK) when l_len is non-negative is 11006 mandated. 828 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fcntl( ) 11007 * In the ERRORS section, the [EINVAL] error condition has the case mandated when the cmd is 11008 invalid, and two [EOVERFLOW] error conditions are added. 11009 The F_GETOWN and F_SETOWN values are added for sockets. 11010 The following changes were made to align with the IEEE P1003.1a draft standard: 11011 * Clarification is added that the extent of the bytes locked is determined prior to the blocking 11012 action. 11013 The DESCRIPTION is updated for alignment with IEEE Std. 1003.1j-2000 by specifying that 11014 fcntl( ) results are unspecified for typed memory objects. 11015 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 829 fcvt( ) System Interfaces 11016 NAME 11017 fcvt - convert a floating-point number to a string (LEGACY) 11018 SYNOPSIS 11019 XSI #include 11020 char *fcvt(double value, int ndigit, int *restrict decpt, | 11021 int *restrict sign); | 11022 | 11023 DESCRIPTION 11024 Refer to ecvt( ). 830 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fdatasync( ) 11025 NAME 11026 fdatasync - synchronize the data of a file (REALTIME) 11027 SYNOPSIS 11028 SIO #include 11029 int fdatasync(int fildes); 11030 11031 DESCRIPTION 11032 The fdatasync( ) function shall force all currently queued I/O operations associated with the file 11033 indicated by file descriptor fildes to the synchronized I/O completion state. 11034 The functionality is as described for fsync( ) (with the symbol _POSIX_SYNCHRONIZED_IO 11035 defined), with the exception that all I/O operations shall be completed as defined for 11036 synchronized I/O data integrity completion. 11037 RETURN VALUE 11038 If successful, the fdatasync( ) function shall return the value 0; otherwise, the function shall return 11039 the value -1 and set errno to indicate the error. If the fdatasync( ) function fails, outstanding I/O 11040 operations are not guaranteed to have been completed. 11041 ERRORS 11042 The fdatasync( ) function shall fail if: 11043 [EBADF] The fildes argument is not a valid file descriptor open for writing. | 11044 [EINVAL] This implementation does not support synchronized I/O for this file. | 11045 In the event that any of the queued I/O operations fail, fdatasync( ) shall return the error 11046 conditions defined for read( ) and write( ). 11047 EXAMPLES 11048 None. 11049 APPLICATION USAGE 11050 None. 11051 RATIONALE 11052 None. 11053 FUTURE DIRECTIONS 11054 None. 11055 SEE ALSO 11056 aio_fsync( ), fcntl( ), fsync( ), open( ), read( ), write( ), the Base Definitions volume of | 11057 IEEE Std. 1003.1-200x, | 11058 CHANGE HISTORY 11059 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 11060 Issue 6 11061 The [ENOSYS] error condition has been removed as stubs need not be provided if an 11062 implementation does not support the Synchronized Input and Output option. | 11063 The fdatasync( ) function is marked as part of the Synchronized Input and Output option. | System Interfaces, Issue 6 831 fdetach( ) System Interfaces 11064 NAME 11065 fdetach - detach a name from a STREAMS-based file descriptor (STREAMS) 11066 SYNOPSIS 11067 XSR #include 11068 int fdetach(const char *path); 11069 11070 DESCRIPTION 11071 The fdetach( ) function detaches a STREAMS-based file from the file to which it was attached by a 11072 previous call to fattach( ). The path argument points to the path name of the attached STREAMS 11073 file. The application shall ensure that the process has appropriate privileges or be the owner of 11074 the file. A successful call to fdetach( ) shall cause all path names that named the attached 11075 STREAMS file to again name the file to which the STREAMS file was attached. All subsequent 11076 operations on path shall operate on the underlying file and not on the STREAMS file. 11077 All open file descriptions established while the STREAMS file was attached to the file referenced 11078 by path shall still refer to the STREAMS file after the fdetach( ) has taken effect. 11079 If there are no open file descriptors or other references to the STREAMS file, then a successful 11080 call to fdetach( ) shall have the same effect as performing the last close( ) on the attached file. 11081 RETURN VALUE 11082 Upon successful completion, fdetach( ) shall return 0; otherwise, it shall return -1 and set errno to 11083 indicate the error. 11084 ERRORS 11085 The fdetach( ) function shall fail if: 11086 [EACCES] Search permission is denied on a component of the path prefix. | 11087 [EINVAL] The path argument names a file that is not currently attached. | 11088 [ELOOP] A loop exists in symbolic links encountered during resolution of the path | 11089 argument. | 11090 [ENAMETOOLONG] | 11091 The size of a path name exceeds {PATH_MAX} or a path name component is | 11092 longer than {NAME_MAX}. | 11093 [ENOENT] A component of path does not name an existing file or path is an empty string. | 11094 [ENOTDIR] A component of the path prefix is not a directory. | 11095 [EPERM] The effective user ID is not the owner of path and the process does not have | 11096 appropriate privileges. | 11097 The fdetach( ) function may fail if: 11098 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during | 11099 resolution of the path argument. | 11100 [ENAMETOOLONG] | 11101 Path name resolution of a symbolic link produced an intermediate result 11102 whose length exceeds {PATH_MAX}. 832 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fdetach( ) 11103 EXAMPLES 11104 Detaching a File 11105 The following example detaches the STREAMS-based file /tmp/named-STREAM from the file to 11106 which it was attached by a previous, successful call to fattach( ). Subsequent calls to open this 11107 file refer to the underlying file, not to the STREAMS file. 11108 #include 11109 ... 11110 char *filename = "/tmp/named-STREAM"; 11111 int ret; 11112 ret = fdetach(filename); 11113 APPLICATION USAGE 11114 None. 11115 RATIONALE 11116 None. 11117 FUTURE DIRECTIONS 11118 None. 11119 SEE ALSO 11120 fattach( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 11121 CHANGE HISTORY 11122 First released in Issue 4, Version 2. 11123 Issue 5 11124 Moved from X/OPEN UNIX extension to BASE. 11125 Issue 6 11126 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. | 11127 The wording of the mandatory [ELOOP] error condition is updated, and a second optional || 11128 [ELOOP] error condition is added. | System Interfaces, Issue 6 833 fdim( ) System Interfaces 11129 NAME | 11130 fdim, fdimf, fdiml - compute positive difference between two floating-point numbers | 11131 SYNOPSIS | 11132 #include | 11133 double fdim(double x, double y); | 11134 float fdimf(float x, float y); | 11135 long double fdiml(long double x, long double y); | 11136 DESCRIPTION | 11137 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 11138 conflict between the requirements described here and the ISO C standard is unintentional. This | 11139 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 11140 These functions shall determine the positive difference between their arguments. If x is greater | 11141 than y, x-y is returned. If x is less than or equal to y, +0 is returned. | 11142 An application wishing to check for error situations should set errno to 0 before calling these | 11143 functions. If errno is non-zero on return, or the return value is NaN, an error has occurred. | 11144 RETURN VALUE | 11145 Upon successful completion, these functions shall return the positive difference value. | 11146 If x or y is NaN, NaN shall be returned and errno may be set to [EDOM]. | 11147 If the magnitude of the result is too large or too small, the numeric result is unspecified and errno | 11148 may be set to [ERANGE]. | 11149 ERRORS | 11150 These functions may fail if: | 11151 [EDOM] The value of x or y is NaN. | 11152 [ERANGE] The magnitude of the result is too large or too small. | 11153 EXAMPLES | 11154 None. | 11155 APPLICATION USAGE | 11156 None. | 11157 RATIONALE | 11158 None. | 11159 FUTURE DIRECTIONS | 11160 None. | 11161 SEE ALSO | 11162 fmax( ), fmin( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 11163 CHANGE HISTORY || 11164 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | 834 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fdopen( ) 11165 NAME 11166 fdopen - associate a stream with a file descriptor 11167 SYNOPSIS 11168 #include 11169 FILE *fdopen(int fildes, const char *mode); 11170 DESCRIPTION 11171 The fdopen( ) function shall associate a stream with a file descriptor. 11172 The mode argument is a character string having one of the following values: 11173 r or rb Open a file for reading. 11174 w or wb Open a file for writing. 11175 a or ab Open a file for writing at end of file. 11176 r+ or rb+ or r+b Open a file for update (reading and writing). 11177 w+ or wb+ or w+b Open a file for update (reading and writing). 11178 a+ or ab+ or a+b Open a file for update (reading and writing) at end of file. 11179 The meaning of these flags is exactly as specified in fopen( ), except that modes beginning with w 11180 do not cause truncation of the file. 11181 Additional values for the mode argument may be supported by an implementation. 11182 The application shall ensure that the mode of the stream as expressed by the type argument is 11183 allowed by the file access mode of the open file description to which fildes refers. The file 11184 position indicator associated with the new stream is set to the position indicated by the file 11185 offset associated with the file descriptor. 11186 The error and end-of-file indicators for the stream shall be cleared. The fdopen( ) function may 11187 cause the st_atime field of the underlying file to be marked for update. 11188 SHM If fildes refers to a shared memory object, the result of the fdopen( ) function is unspecified. 11189 TYM If fildes refers to a typed memory object, the result of the fdopen( ) function is unspecified. 11190 The fdopen( ) function shall preserve the offset maximum previously set for the open file 11191 description corresponding to fildes. 11192 RETURN VALUE 11193 Upon successful completion, fdopen( ) shall return a pointer to a stream; otherwise, a null pointer 11194 shall be returned and errno set to indicate the error. 11195 ERRORS 11196 The fdopen( ) function may fail if: 11197 [EBADF] The fildes argument is not a valid file descriptor. | 11198 [EINVAL] The mode argument is not a valid mode. | 11199 [EMFILE] {FOPEN_MAX} streams are currently open in the calling process. | 11200 [EMFILE] {STREAM_MAX} streams are currently open in the calling process. | 11201 [ENOMEM] Insufficient space to allocate a buffer. | System Interfaces, Issue 6 835 fdopen( ) System Interfaces 11202 EXAMPLES 11203 None. 11204 APPLICATION USAGE 11205 File descriptors are obtained from calls like open( ), dup( ), creat( ), or pipe( ), which open files but 11206 do not return streams. 11207 RATIONALE 11208 The file descriptor may have been obtained from open( ), creat( ), pipe( ), dup( ), or fcntl( ); 11209 inherited through fork( ) or exec; or perhaps obtained by implementation-defined means, such as | 11210 the 4.3 BSD socket( ) call. | 11211 The meanings of the type arguments of fdopen( ) and fopen( ) differ. With fdopen( ), open for write 11212 (w or w+) does not truncate, and append (a or a+) cannot create for writing. There is no need for b 11213 in the format due to the equivalence of binary and text files in this volume of 11214 IEEE Std. 1003.1-200x. Although not explicitly required by this volume of IEEE Std. 1003.1-200x, 11215 a good implementation of append (a) mode would cause the O_APPEND flag to be set. 11216 FUTURE DIRECTIONS 11217 None. 11218 SEE ALSO 11219 fclose( ), fopen( ), open( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , Section | 11220 2.5.1 (on page 535) 11221 CHANGE HISTORY 11222 First released in Issue 1. Derived from Issue 1 of the SVID. | 11223 Issue 4 11224 In the DESCRIPTION, the use and settings of the mode argument are changed to include binary 11225 streams and are marked as extensions. 11226 All errors identified in the ERRORS section are marked as extensions, and the [EMFILE] error is 11227 added. 11228 The APPLICATION USAGE section is added. 11229 The following change is incorporated for alignment with the ISO POSIX-1 standard: 11230 * The type of argument mode is changed from char* to const char*. 11231 Issue 5 11232 The DESCRIPTION is updated for alignment with the POSIX Realtime Extension. 11233 Large File Summit extensions are added. 11234 Issue 6 11235 The following new requirements on POSIX implementations derive from alignment with the 11236 Single UNIX Specification: 11237 * In the DESCRIPTION, the use and setting of the mode argument are changed to include 11238 binary streams. 11239 * In the DESCRIPTION, text is added for large file support to indicate setting of the offset 11240 maximum in the open file description. 11241 * All errors identified in the ERRORS section are added. 11242 * In the DESCRIPTION, text is added that the fdopen( ) function may cause st_atime to be 11243 updated. 836 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fdopen( ) 11244 The following changes were made to align with the IEEE P1003.1a draft standard: 11245 * Clarification is added that it is the responsibility of the application to ensure that the mode is 11246 compatible with the open file descriptor. 11247 The DESCRIPTION is updated for alignment with IEEE Std. 1003.1j-2000 by specifying that | 11248 fdopen( ) results are unspecified for typed memory objects. System Interfaces, Issue 6 837 feclearexcept( ) System Interfaces 11249 NAME | 11250 feclearexcept - clear floating-point exception | 11251 SYNOPSIS | 11252 #include | 11253 void feclearexcept(int excepts); | 11254 DESCRIPTION | 11255 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 11256 conflict between the requirements described here and the ISO C standard is unintentional. This | 11257 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 11258 The feclearexcept( ) function shall clear the supported floating-point exceptions represented by | 11259 excepts. | 11260 RETURN VALUE | 11261 None. | 11262 ERRORS | 11263 No errors are defined. | 11264 EXAMPLES | 11265 None. | 11266 APPLICATION USAGE | 11267 None. | 11268 RATIONALE | 11269 None. | 11270 FUTURE DIRECTIONS | 11271 None. | 11272 SEE ALSO | 11273 fegetexceptflag( ), feraiseexcept( ), fesetexceptflag( ), fetestexcept( ), the Base Definitions volume of | 11274 IEEE Std. 1003.1-200x, | 11275 CHANGE HISTORY || 11276 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | 838 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fegetenv( ) 11277 NAME | 11278 fegetenv, fesetenv - get and set current floating-point environment | 11279 SYNOPSIS | 11280 #include | 11281 void fegetenv(fenv_t *envp); | 11282 void fesetenv(const fenv_t *envp); | 11283 DESCRIPTION | 11284 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 11285 conflict between the requirements described here and the ISO C standard is unintentional. This | 11286 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 11287 The fegetenv( ) function shall store the current floating-point environment in the object pointed to | 11288 by envp. | 11289 The fesetenv( ) function shall establish the floating-point environment represented by the object | 11290 pointed to by envp. The argument envp shall point to an object set by a call to fegetenv( ) or | 11291 feholdexcept( ), or equal a floating-point environment macro. The fesetenv( ) function does not | 11292 raise floating-point exceptions, but only installs the state of the floating-point status flags | 11293 represented through its argument. | 11294 RETURN VALUE | 11295 None. | 11296 ERRORS | 11297 No errors are defined. | 11298 EXAMPLES | 11299 None. | 11300 APPLICATION USAGE | 11301 None. | 11302 RATIONALE | 11303 None. | 11304 FUTURE DIRECTIONS | 11305 None. | 11306 SEE ALSO | 11307 feholdexcept( ), feupdateenv( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 11308 CHANGE HISTORY || 11309 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 839 fegetexceptflag( ) System Interfaces 11310 NAME | 11311 fegetexceptflag, fesetexceptflag - get and set floating-point status flags | 11312 SYNOPSIS | 11313 #include | 11314 void fegetexceptflag(fexcept_t *flagp, int excepts); | 11315 void fesetexceptflag(const fexcept_t *flagp, int excepts); | 11316 DESCRIPTION | 11317 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 11318 conflict between the requirements described here and the ISO C standard is unintentional. This | 11319 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 11320 The fegetexceptflag( ) function shall store an implementation-defined representation of the states | 11321 of the floating-point status flags indicated by the argument excepts in the object pointed to by the | 11322 argument flagp. | 11323 The fesetexceptflag( ) function shall set the floating-point status flags indicated by the argument | 11324 excepts to the states stored in the object pointed to by flagp. The value pointed to by flagp shall | 11325 have been set by a previous call to fegetexceptflag( ) whose second argument represented at least | 11326 those floating-point exceptions represented by the argument excepts. This function does not | 11327 raise floating-point exceptions, but only sets the state of the flags. | 11328 RETURN VALUE | 11329 None. | 11330 ERRORS | 11331 No errors are defined. | 11332 EXAMPLES | 11333 None. | 11334 APPLICATION USAGE | 11335 None. | 11336 RATIONALE | 11337 None. | 11338 FUTURE DIRECTIONS | 11339 None. | 11340 SEE ALSO | 11341 feclearexcept( ), feraiseexcept( ), fetestexcept( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 11342 | 11343 CHANGE HISTORY || 11344 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | 840 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fegetround( ) 11345 NAME | 11346 fegetround, fesetround - get and set current rounding direction | 11347 SYNOPSIS | 11348 #include | 11349 int fegetround(void); | 11350 int fesetround(int round); | 11351 DESCRIPTION | 11352 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 11353 conflict between the requirements described here and the ISO C standard is unintentional. This | 11354 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 11355 The fegetround( ) function shall get the current rounding direction. | 11356 The fesetround( ) function shall establish the rounding direction represented by its argument | 11357 round. If the argument is not equal to the value of a rounding direction macro, the rounding | 11358 direction is not changed. | 11359 RETURN VALUE | 11360 The fegetround( ) function shall return the value of the rounding direction macro representing the | 11361 current rounding direction or a negative value if there is no such rounding direction macro or | 11362 the current rounding direction is not determinable. | 11363 The fesetround( ) function shall return a zero value if and only if the argument is equal to a | 11364 rounding direction macro (that is, if and only if the requested rounding direction was | 11365 established). | 11366 ERRORS | 11367 No errors are defined. | 11368 EXAMPLES | 11369 The following example saves, sets, and restores the rounding direction, reporting an error and | 11370 aborting if setting the rounding direction fails: | 11371 #include | 11372 #include | 11373 void f(int round_dir) | 11374 { | 11375 #pragma STDC FENV_ACCESS ON | 11376 int save_round; | 11377 int setround_ok; | 11378 save_round = fegetround(); | 11379 setround_ok = fesetround(round_dir); | 11380 assert(setround_ok == 0); | 11381 /* ... */ | 11382 fesetround(save_round); | 11383 /* ... */ | 11384 } | 11385 APPLICATION USAGE | 11386 None. | 11387 RATIONALE | 11388 None. | System Interfaces, Issue 6 841 fegetround( ) System Interfaces 11389 FUTURE DIRECTIONS | 11390 None. | 11391 SEE ALSO | 11392 The Base Definitions volume of IEEE Std. 1003.1-200x, | 11393 CHANGE HISTORY || 11394 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | 842 Technical Standard (2000) (Draft July 31, 2000) System Interfaces feholdexcept( ) 11395 NAME | 11396 feholdexcept - save current floating-point environment | 11397 SYNOPSIS | 11398 #include | 11399 int feholdexcept(fenv_t *envp); | 11400 DESCRIPTION | 11401 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 11402 conflict between the requirements described here and the ISO C standard is unintentional. This | 11403 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 11404 The feholdexcept( ) function shall save the current floating-point environment in the object | 11405 pointed to by envp, clear the floating-point status flags, and then install a non-stop (continue on | 11406 floating-point exceptions) mode, if available, for all floating-point exceptions. | 11407 RETURN VALUE | 11408 The feholdexcept( ) function shall return zero if and only if non-stop floating-point exception | 11409 handling was successfully installed. | 11410 ERRORS | 11411 No errors are defined. | 11412 EXAMPLES | 11413 None. | 11414 APPLICATION USAGE | 11415 None. | 11416 RATIONALE | 11417 The feholdexcept( ) function should be effective on typical IEC 60559: 1989 standard | 11418 implementations which have the default non-stop mode and at least one other mode for trap | 11419 handling or aborting. If the implementation provides only the non-stop mode, then installing the | 11420 non-stop mode is trivial. | 11421 FUTURE DIRECTIONS | 11422 None. | 11423 SEE ALSO | 11424 fegetenv( ), fesetenv( ), feupdateenv( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 11425 | 11426 CHANGE HISTORY || 11427 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 843 feof( ) System Interfaces 11428 NAME 11429 feof - test end-of-file indicator on a stream 11430 SYNOPSIS 11431 #include 11432 int feof(FILE *stream); 11433 DESCRIPTION 11434 CX The functionality described on this reference page is aligned with the ISO C standard. Any 11435 conflict between the requirements described here and the ISO C standard is unintentional. This 11436 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 11437 The feof( ) function shall test the end-of-file indicator for the stream pointed to by stream. 11438 RETURN VALUE 11439 The feof( ) function shall return non-zero if and only if the end-of-file indicator is set for stream. 11440 ERRORS 11441 No errors are defined. 11442 EXAMPLES 11443 None. 11444 APPLICATION USAGE 11445 None. 11446 RATIONALE 11447 None. 11448 FUTURE DIRECTIONS 11449 None. 11450 SEE ALSO 11451 clearerr( ), ferror( ), fopen( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 11452 CHANGE HISTORY 11453 First released in Issue 1. Derived from Issue 1 of the SVID. | 11454 Issue 4 11455 The ERRORS section is rewritten, such that no error return values are now defined for this | 11456 function. 844 Technical Standard (2000) (Draft July 31, 2000) System Interfaces feraiseexcept( ) 11457 NAME | 11458 feraiseexcept - raise floating-point exception | 11459 SYNOPSIS | 11460 #include | 11461 void feraiseexcept(int excepts); | 11462 DESCRIPTION | 11463 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 11464 conflict between the requirements described here and the ISO C standard is unintentional. This | 11465 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 11466 The feraiseexcept( ) function shall raise the supported floating-point exceptions represented by | 11467 the argument excepts. The order in which these floating-point exceptions are raised is | 11468 unspecified. Whether the feraiseexcept( ) function additionally raises the inexact floating-point | 11469 exception whenever it raises the overflow or underflow floating-point exception is | 11470 implementation-defined. | 11471 RETURN VALUE | 11472 None. | 11473 ERRORS | 11474 No errors are defined. | 11475 EXAMPLES | 11476 None. | 11477 APPLICATION USAGE | 11478 The effect is intended to be similar to that of floating-point exceptions raised by arithmetic | 11479 operations. Hence, enabled traps for floating-point exceptions raised by this function are taken. | 11480 RATIONALE | 11481 Raising overflow or underflow is allowed to also raise inexact because on some architectures the | 11482 only practical way to raise an exception is to execute an instruction that has the exception as a | 11483 side effect. The function is not restricted to accept only valid coincident expressions for atomic | 11484 operations, so the function can be used to raise exceptions accrued over several operations. | 11485 FUTURE DIRECTIONS | 11486 None. | 11487 SEE ALSO | 11488 feclearexcept( ), fegetexceptflag( ), fesetexceptflag( ), fetestexcept( ), the Base Definitions volume of | 11489 IEEE Std. 1003.1-200x, | 11490 CHANGE HISTORY || 11491 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 845 ferror( ) System Interfaces 11492 NAME 11493 ferror - test error indicator on a stream 11494 SYNOPSIS 11495 #include 11496 int ferror(FILE *stream); 11497 DESCRIPTION 11498 CX The functionality described on this reference page is aligned with the ISO C standard. Any 11499 conflict between the requirements described here and the ISO C standard is unintentional. This 11500 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 11501 The ferror( ) function shall test the error indicator for the stream pointed to by stream. 11502 RETURN VALUE 11503 The ferror( ) function shall return non-zero if and only if the error indicator is set for stream. 11504 ERRORS 11505 No errors are defined. 11506 EXAMPLES 11507 None. 11508 APPLICATION USAGE 11509 None. 11510 RATIONALE 11511 None. 11512 FUTURE DIRECTIONS 11513 None. 11514 SEE ALSO 11515 clearerr( ), feof( ), fopen( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 11516 CHANGE HISTORY 11517 First released in Issue 1. Derived from Issue 1 of the SVID. | 11518 Issue 4 11519 The ERRORS section is rewritten, such that no error return values are now defined for this | 11520 function. 846 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fesetenv( ) 11521 NAME | 11522 fesetenv - set current floating-point environment | 11523 SYNOPSIS | 11524 #include | 11525 void fesetenv(const fenv_t *envp); | 11526 DESCRIPTION || 11527 Refer to fegetenv( ). | System Interfaces, Issue 6 847 fesetexceptflag( ) System Interfaces 11528 NAME | 11529 fesetexceptflag - set floating-point status flags | 11530 SYNOPSIS | 11531 #include | 11532 void fesetexceptflag(const fexcept_t *flagp, int excepts); | 11533 DESCRIPTION || 11534 Refer to fegetexceptflag( ). | 848 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fesetround( ) 11535 NAME | 11536 fesetround - set current rounding direction | 11537 SYNOPSIS | 11538 #include | 11539 int fesetround(int round); | 11540 DESCRIPTION || 11541 Refer to fegetround( ). | System Interfaces, Issue 6 849 fetestexcept( ) System Interfaces 11542 NAME | 11543 fetestexcept - test floating-point exception flags | 11544 SYNOPSIS | 11545 #include | 11546 int fetestexcept(int excepts); | 11547 DESCRIPTION | 11548 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 11549 conflict between the requirements described here and the ISO C standard is unintentional. This | 11550 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 11551 The fetestexcept( ) function shall determine which of a specified subset of the floating-point | 11552 exception flags are currently set. The excepts argument specifies the floating-point status flags to | 11553 be queried. | 11554 RETURN VALUE | 11555 The fetestexcept( ) function shall return the value of the bitwise-inclusive OR of the floating-point | 11556 exception macros corresponding to the currently set floating-point exceptions included in | 11557 excepts. | 11558 ERRORS | 11559 No errors are defined. | 11560 EXAMPLES | 11561 The following example calls function f( ) if an invalid exception is set, and then function g( ) if an | 11562 overflow exception is set: | 11563 #include | 11564 /* ... */ | 11565 { | 11566 #pragma STDC FENV_ACCESS ON | 11567 int set_excepts; | 11568 feclearexcept(FE_INVALID | FE_OVERFLOW); | 11569 // maybe raise exceptions | 11570 set_excepts = fetestexcept(FE_INVALID | FE_OVERFLOW); | 11571 if (set_excepts & FE_INVALID) f(); | 11572 if (set_excepts & FE_OVERFLOW) g(); | 11573 /* ... */ | 11574 } | 11575 APPLICATION USAGE | 11576 None. | 11577 RATIONALE | 11578 None. | 11579 FUTURE DIRECTIONS | 11580 None. | 11581 SEE ALSO | 11582 feclearexcept( ), fegetexceptflag( ), feraiseexcept( ), the Base Definitions volume of | 11583 IEEE Std. 1003.1-200x, | 850 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fetestexcept( ) 11584 CHANGE HISTORY || 11585 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 851 feupdateenv( ) System Interfaces 11586 NAME | 11587 feupdateenv - update floating-point environment | 11588 SYNOPSIS | 11589 #include | 11590 void feupdateenv(const fenv_t *envp); | 11591 DESCRIPTION | 11592 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 11593 conflict between the requirements described here and the ISO C standard is unintentional. This | 11594 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 11595 The feupdateenv( ) function shall save the currently raised floating-point exceptions in its | 11596 automatic storage, install the floating-point environment represented by the object pointed to by | 11597 envp, and then raise the saved floating-point exceptions. The argument envp shall point to an | 11598 object set by a call to feholdexcept( ) or fegetenv( ), or equal a floating-point environment macro. | 11599 RETURN VALUE | 11600 None. | 11601 ERRORS | 11602 No errors are defined. | 11603 EXAMPLES | 11604 The following example shows sample code to hide spurious underflow floating-point | 11605 exceptions: | 11606 #include | 11607 double f(double x) | 11608 { | 11609 #pragma STDC FENV_ACCESS ON | 11610 double result; | 11611 fenv_t save_env; | 11612 feholdexcept(&save_env); | 11613 // compute result | 11614 if (/* test spurious underflow */) | 11615 feclearexcept(FE_UNDERFLOW); | 11616 feupdateenv(&save_env); | 11617 return result; | 11618 } | 11619 APPLICATION USAGE | 11620 None. | 11621 RATIONALE | 11622 None. | 11623 FUTURE DIRECTIONS | 11624 None. | 11625 SEE ALSO | 11626 fegetenv( ), feholdexcept( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 11627 CHANGE HISTORY || 11628 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | 852 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fflush( ) 11629 NAME 11630 fflush - flush a stream 11631 SYNOPSIS 11632 #include 11633 int fflush(FILE *stream); 11634 DESCRIPTION 11635 CX The functionality described on this reference page is aligned with the ISO C standard. Any 11636 conflict between the requirements described here and the ISO C standard is unintentional. This 11637 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 11638 If stream points to an output stream or an update stream in which the most recent operation was 11639 CX not input, fflush( ) causes any unwritten data for that stream to be written to the file, and the 11640 st_ctime and st_mtime fields of the underlying file are marked for update. 11641 If stream is a null pointer, fflush( ) shall perform this flushing action on all streams for which the 11642 behavior is defined above. 11643 RETURN VALUE 11644 Upon successful completion, fflush( ) shall return 0; otherwise, it shall set the error indicator for | 11645 CX the stream, return EOF, and set errno to indicate the error. | 11646 ERRORS 11647 The fflush( ) function shall fail if: 11648 CX [EAGAIN] The O_NONBLOCK flag is set for the file descriptor underlying stream and the | 11649 process would be delayed in the write operation. 11650 CX [EBADF] The file descriptor underlying stream is not valid. | 11651 CX [EFBIG] An attempt was made to write a file that exceeds the maximum file size. | 11652 XSI [EFBIG] An attempt was made to write a file that exceeds the process' file size limit. | 11653 CX [EFBIG] The file is a regular file and an attempt was made to write at or beyond the | 11654 offset maximum associated with the corresponding stream. 11655 CX [EINTR] The fflush( ) function was interrupted by a signal. | 11656 CX [EIO] The process is a member of a background process group attempting to write | 11657 to its controlling terminal, TOSTOP is set, the process is neither ignoring nor 11658 blocking SIGTTOU, and the process group of the process is orphaned. This 11659 error may also be returned under implementation-defined conditions. | 11660 CX [ENOSPC] There was no free space remaining on the device containing the file. | 11661 CX [EPIPE] An attempt is made to write to a pipe or FIFO that is not open for reading by | 11662 any process. A SIGPIPE signal shall also be sent to the thread. 11663 The fflush( ) function may fail if: 11664 CX [ENXIO] A request was made of a nonexistent device, or the request was outside the | 11665 capabilities of the device. System Interfaces, Issue 6 853 fflush( ) System Interfaces 11666 EXAMPLES 11667 Sending Prompts to Standard Output 11668 The following example uses printf( ) calls to print a series of prompts for information the user 11669 must enter from standard input. The fflush( ) calls force the output to standard output. The 11670 fflush( ) function is used because standard output is usually buffered and the prompt may not 11671 immediately be printed on the output or terminal. The gets( ) calls read strings from standard 11672 input and place the results in variables, for use later in the program 11673 #include 11674 ... 11675 char user[100]; 11676 char oldpasswd[100]; 11677 char newpasswd[100]; 11678 ... 11679 printf("User name: "); 11680 fflush(stdout); 11681 gets(user); 11682 printf("Old password: "); 11683 fflush(stdout); 11684 gets(oldpasswd); 11685 printf("New password: "); 11686 fflush(stdout); 11687 gets(newpasswd); 11688 ... 11689 APPLICATION USAGE 11690 None. 11691 RATIONALE 11692 Data buffered by the system may make determining the validity of the position of the current 11693 file descriptor impractical. Thus, enforcing the repositioning of the file descriptor after fflush( ) 11694 on streams open for read( ) is not mandated by IEEE Std. 1003.1-200x. 11695 FUTURE DIRECTIONS 11696 None. 11697 SEE ALSO 11698 getrlimit( ), ulimit( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 11699 CHANGE HISTORY 11700 First released in Issue 1. Derived from Issue 1 of the SVID. | 11701 Issue 4 11702 The following change is incorporated for alignment with the ISO C standard: 11703 * The DESCRIPTION is changed to describe the behavior of fflush( ) if stream is a null pointer. 11704 The following changes are incorporated for alignment with the ISO POSIX-1 standard: 11705 * The following two paragraphs are withdrawn from the DESCRIPTION (by POSIX as well as 11706 X/Open) because of the possibility of causing applications to malfunction, and the 11707 impossibility of implementing these mechanisms for pipes: 854 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fflush( ) 11708 If the stream is open for reading, any unread data buffered in the stream is discarded. 11709 For a stream open for reading, if the file is not already at EOF, and the file is one capable 11710 of seeking, the file offset of the underlying open file description is adjusted so that the 11711 next operation on the open file description deals with the byte after the last one read 11712 from, or written to, the stream being flushed. 11713 * The [EFBIG] error is marked to indicate the extensions. 11714 Issue 5 11715 Large File Summit extensions are added. 11716 Issue 6 11717 Extensions beyond the ISO C standard are now marked. 11718 The following new requirements on POSIX implementations derive from alignment with the 11719 Single UNIX Specification: 11720 * The [EFBIG] error is added as part of the large file support extensions. 11721 * The [ENXIO] optional error condition is added. 11722 The RETURN VALUE section is updated to note that the error indicator shall be set for the | 11723 stream. This is for alignment with the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 855 ffs( ) System Interfaces 11724 NAME 11725 ffs - find first set bit 11726 Notes to Reviewers 11727 This section with side shading will not appear in the final copy. - Ed. 11728 This function or these functions are recommended to become mandatory parts of POSIX.1 in the 11729 next draft. 11730 SYNOPSIS 11731 XSI #include 11732 int ffs(int i); 11733 11734 DESCRIPTION 11735 The ffs( ) function shall find the first bit set (beginning with the least significant bit) in i, and 11736 return the index of that bit. Bits are numbered starting at one (the least significant bit). 11737 RETURN VALUE 11738 The ffs( ) function shall return the index of the first bit set. If i is 0, then ffs( ) shall return 0. 11739 ERRORS 11740 No errors are defined. 11741 EXAMPLES 11742 None. 11743 APPLICATION USAGE 11744 None. 11745 RATIONALE 11746 None. 11747 FUTURE DIRECTIONS 11748 None. 11749 SEE ALSO 11750 The Base Definitions volume of IEEE Std. 1003.1-200x, | 11751 CHANGE HISTORY 11752 First released in Issue 4, Version 2. 11753 Issue 5 11754 Moved from X/OPEN UNIX extension to BASE. 856 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fgetc( ) 11755 NAME 11756 fgetc - get a byte from a stream 11757 SYNOPSIS 11758 #include 11759 int fgetc(FILE *stream); 11760 DESCRIPTION 11761 CX The functionality described on this reference page is aligned with the ISO C standard. Any 11762 conflict between the requirements described here and the ISO C standard is unintentional. This 11763 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 11764 If the end-of-file indicator for the input stream pointed to by stream is not set and a next | 11765 character is present, the fgetc( ) function obtains the next byte (if present) as an unsigned char | 11766 converted to an int, from the input stream pointed to by stream, and advances the associated file 11767 position indicator for the stream (if defined). 11768 CX The fgetc( ) function may mark the st_atime field of the file associated with stream for update. The 11769 st_atime field shall be marked for update by the first successful execution of fgetc( ), fgets( ), 11770 fgetwc( ), fgetws( ), fread( ), fscanf( ), getc( ), getchar( ), gets( ), or scanf( ) using stream that returns 11771 data not supplied by a prior call to ungetc( ) or ungetwc( ). 11772 RETURN VALUE 11773 Upon successful completion, fgetc( ) shall return the next byte from the input stream pointed to 11774 by stream. If the end-of-file indicator for the stream is set, or if the stream is at end-of-file, the | 11775 end-of-file indicator for the stream shall be set and fgetc( ) shall return EOF. If a read error occurs, | 11776 CX the error indicator for the stream shall be set, fgetc( ) shall return EOF, and shall set errno to 11777 indicate the error. 11778 ERRORS 11779 The fgetc( ) function shall fail if data needs to be read and: 11780 CX [EAGAIN] The O_NONBLOCK flag is set for the file descriptor underlying stream and the | 11781 process would be delayed in the fgetc( ) operation. 11782 CX [EBADF] The file descriptor underlying stream is not a valid file descriptor open for | 11783 reading. 11784 CX [EINTR] The read operation was terminated due to the receipt of a signal, and no data | 11785 was transferred. 11786 CX [EIO] A physical I/O error has occurred, or the process is in a background process | 11787 group attempting to read from its controlling terminal, and either the process 11788 is ignoring or blocking the SIGTTIN signal or the process group is orphaned. | 11789 This error may also be generated for implementation-defined reasons. | 11790 CX [EOVERFLOW] The file is a regular file and an attempt was made to read at or beyond the | 11791 offset maximum associated with the corresponding stream. 11792 The fgetc( ) function may fail if: 11793 CX [ENOMEM] Insufficient storage space is available. | 11794 CX [ENXIO] A request was made of a nonexistent device, or the request was outside the | 11795 capabilities of the device. System Interfaces, Issue 6 857 fgetc( ) System Interfaces 11796 EXAMPLES 11797 None. 11798 APPLICATION USAGE 11799 If the integer value returned by fgetc( ) is stored into a variable of type char and then compared 11800 against the integer constant EOF, the comparison may never succeed, because sign-extension of 11801 a variable of type char on widening to integer is implementation-defined. | 11802 The ferror( ) or feof( ) functions must be used to distinguish between an error condition and an 11803 end-of-file condition. 11804 RATIONALE 11805 None. 11806 FUTURE DIRECTIONS 11807 None. 11808 SEE ALSO 11809 feof( ), ferror( ), fopen( ), getchar( ), getc( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 11810 11811 CHANGE HISTORY 11812 First released in Issue 1. Derived from Issue 1 of the SVID. | 11813 Issue 4 11814 In the DESCRIPTION: 11815 * The text is changed to make it clear that the function returns a byte value. 11816 * The list of functions that may cause the st_atime field to be updated is revised. 11817 In the ERRORS section, text is added to indicate that error returns are only generated when data 11818 needs to be read into the stream buffer. 11819 Also in the ERRORS section, in previous issues generation of the [EIO] error depended on 11820 whether or not an implementation supported Job Control. This functionality is now defined as 11821 mandatory. 11822 The [ENXIO] and [ENOMEM] errors are marked as extensions. 11823 In the APPLICATION USAGE section, text is added to indicate how an application can 11824 distinguish between an error condition and an end-of-file condition. 11825 The description of [EINTR] is amended. 11826 Issue 4, Version 2 11827 In the ERRORS section, the description of [EIO] is updated to include the case where a physical 11828 I/O error occurs. 11829 Issue 5 11830 Large File Summit extensions are added. 11831 Issue 6 11832 Extensions beyond the ISO C standard are now marked. 11833 The following new requirements on POSIX implementations derive from alignment with the 11834 Single UNIX Specification: 11835 * The [EIO] and [EOVERFLOW] mandatory error conditions are added. 11836 * The [ENOMEM] and [ENXIO] optional error conditions are added. 858 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fgetc( ) 11837 The following changes are made for alignment with the ISO/IEC 9899: 1999 standard: | 11838 * The DESCRIPTION is updated to clarify the behavior when the end-of-file indicator for the | 11839 input stream is not set. | 11840 * The RETURN VALUE section is updated to note that the error indicator shall be set for the | | 11841 stream. | System Interfaces, Issue 6 859 fgetpos( ) System Interfaces 11842 NAME 11843 fgetpos - get current file position information 11844 SYNOPSIS 11845 #include 11846 int fgetpos(FILE *restrict stream, fpos_t *restrict pos); | 11847 DESCRIPTION | 11848 CX The functionality described on this reference page is aligned with the ISO C standard. Any 11849 conflict between the requirements described here and the ISO C standard is unintentional. This 11850 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 11851 The fgetpos( ) function shall store the current value of the file position indicator for the stream 11852 pointed to by stream in the object pointed to by pos. The value stored contains unspecified 11853 information usable by fsetpos( ) for repositioning the stream to its position at the time of the call 11854 to fgetpos( ). 11855 RETURN VALUE 11856 Upon successful completion, fgetpos( ) shall return 0; otherwise, it shall return a non-zero value 11857 and set errno to indicate the error. 11858 ERRORS 11859 The fgetpos( ) function shall fail if: 11860 CX [EOVERFLOW] The current value of the file position cannot be represented correctly in an | 11861 object of type fpos_t. 11862 The fgetpos( ) function may fail if: 11863 CX [EBADF] The file descriptor underlying stream is not valid. | 11864 CX [ESPIPE] The file descriptor underlying stream is associated with a pipe, FIFO, or socket. | 11865 11866 EXAMPLES 11867 None. 11868 APPLICATION USAGE 11869 None. 11870 RATIONALE 11871 None. 11872 FUTURE DIRECTIONS 11873 None. 11874 SEE ALSO 11875 fopen( ), ftell( ), rewind( ), ungetc( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 11876 11877 CHANGE HISTORY 11878 First released in Issue 4. Derived from the ISO C standard. | 11879 Issue 5 11880 Large File Summit extensions are added. 11881 Issue 6 11882 Extensions beyond the ISO C standard are now marked. 11883 The following new requirements on POSIX implementations derive from alignment with the 11884 Single UNIX Specification: 860 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fgetpos( ) 11885 * The [EIO] mandatory error condition is added. 11886 * The [EBADF] and [ESPIPE] optional error conditions are added. 11887 An additional [ESPIPE] error condition is added for sockets. | 11888 The prototype for fgetpos( ) is changed for alignment with the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 861 fgets( ) System Interfaces 11889 NAME 11890 fgets - get a string from a stream 11891 SYNOPSIS 11892 #include 11893 char *fgets(char *restrict s, int n, FILE *restrict stream); | 11894 DESCRIPTION | 11895 CX The functionality described on this reference page is aligned with the ISO C standard. Any 11896 conflict between the requirements described here and the ISO C standard is unintentional. This 11897 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 11898 The fgets( ) function shall read bytes from stream into the array pointed to by s, until n-1 bytes 11899 are read, or a character is read and transferred to s, or an end-of-file condition is 11900 encountered. The string is then terminated with a null byte. 11901 CX The fgets( ) function may mark the st_atime field of the file associated with stream for update. The 11902 st_atime field shall be marked for update by the first successful execution of fgetc( ), fgets( ), 11903 fgetwc( ), fgetws( ), fread( ), fscanf( ), getc( ), getchar( ), gets( ), or scanf( ) using stream that returns 11904 data not supplied by a prior call to ungetc( ) or ungetwc( ). 11905 RETURN VALUE 11906 Upon successful completion, fgets( ) shall return s. If the stream is at end-of-file, the end-of-file 11907 indicator for the stream shall be set and fgets( ) shall return a null pointer. If a read error occurs, 11908 CX the error indicator for the stream shall be set, fgets( ) shall return a null pointer, and shall set 11909 errno to indicate the error. 11910 ERRORS 11911 Refer to fgetc( ). 11912 EXAMPLES 11913 Reading Input 11914 The following example uses fgets( ) to read each line of input. {LINE_MAX}, which defines the 11915 maximum size of the input line, is defined in the header. 11916 #include 11917 ... 11918 char line[LINE_MAX]; 11919 ... 11920 while (fgets(line, LINE_MAX, fp) != NULL) { 11921 ... 11922 } 11923 ... 11924 APPLICATION USAGE 11925 None. 11926 RATIONALE 11927 None. 11928 FUTURE DIRECTIONS 11929 None. 862 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fgets( ) 11930 SEE ALSO 11931 fopen( ), fread( ), gets( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 11932 CHANGE HISTORY 11933 First released in Issue 1. Derived from Issue 1 of the SVID. | 11934 Issue 4 11935 In the DESCRIPTION, the text is changed to make it clear that the function reads bytes rather 11936 than (possibly multi-byte) characters, and the list of functions that may cause the st_atime field to 11937 be updated is revised. 11938 Issue 6 11939 Extensions beyond the ISO C standard are now marked. | 11940 The prototype for fgets( ) is changed for alignment with the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 863 fgetwc( ) System Interfaces 11941 NAME 11942 fgetwc - get a wide-character code from a stream 11943 SYNOPSIS 11944 #include 11945 #include 11946 wint_t fgetwc(FILE *stream); 11947 DESCRIPTION 11948 CX The functionality described on this reference page is aligned with the ISO C standard. Any 11949 conflict between the requirements described here and the ISO C standard is unintentional. This 11950 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 11951 The fgetwc( ) function shall obtain the next character (if present) from the input stream pointed to 11952 by stream, convert that to the corresponding wide-character code, and advance the associated 11953 file position indicator for the stream (if defined). 11954 If an error occurs, the resulting value of the file position indicator for the stream is 11955 indeterminate. 11956 CX The fgetwc( ) function may mark the st_atime field of the file associated with stream for update. 11957 The st_atime field shall be marked for update by the first successful execution of fgetc( ), fgets( ), 11958 fgetwc( ), fgetws( ), fread( ), fscanf( ), getc( ), getchar( ), gets( ), or scanf( ) using stream that returns 11959 data not supplied by a prior call to ungetc( ) or ungetwc( ). 11960 RETURN VALUE 11961 Upon successful completion, the fgetwc( ) function shall return the wide-character code of the 11962 character read from the input stream pointed to by stream converted to a type wint_t. If the 11963 stream is at end-of-file, the end-of-file indicator for the stream shall be set and fgetwc( ) shall 11964 return WEOF. If a read error occurs, the error indicator for the stream shall be set, fgetwc( ) shall 11965 CX return WEOF, and shall set errno to indicate the error. 11966 ERRORS 11967 The fgetwc( ) function shall fail if data needs to be read and: 11968 CX [EAGAIN] The O_NONBLOCK flag is set for the file descriptor underlying stream and the | 11969 process would be delayed in the fgetwc( ) operation. 11970 CX [EBADF] The file descriptor underlying stream is not a valid file descriptor open for | 11971 reading. 11972 CX [EINTR] The read operation was terminated due to the receipt of a signal, and no data | 11973 was transferred. 11974 CX [EIO] A physical I/O error has occurred, or the process is in a background process | 11975 group attempting to read from its controlling terminal, and either the process 11976 is ignoring or blocking the SIGTTIN signal or the process group is orphaned. | 11977 This error may also be generated for implementation-defined reasons. | 11978 CX [EOVERFLOW] The file is a regular file and an attempt was made to read at or beyond the | 11979 offset maximum associated with the corresponding stream. 11980 The fgetwc( ) function may fail if: 11981 CX [ENOMEM] Insufficient storage space is available. | 11982 CX [ENXIO] A request was made of a nonexistent device, or the request was outside the | 11983 capabilities of the device. 864 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fgetwc( ) 11984 CX [EILSEQ] The data obtained from the input stream does not form a valid character. | 11985 EXAMPLES 11986 None. 11987 APPLICATION USAGE 11988 The ferror( ) or feof( ) functions must be used to distinguish between an error condition and an 11989 end-of-file condition. 11990 RATIONALE 11991 None. 11992 FUTURE DIRECTIONS 11993 None. 11994 SEE ALSO 11995 feof( ), ferror( ), fopen( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , | 11996 11997 CHANGE HISTORY 11998 First released in Issue 4. Derived from the MSE working draft. | 11999 Issue 4, Version 2 12000 In the ERRORS section, the description of [EIO] is updated to include the case where a physical 12001 I/O error occurs. 12002 Issue 5 12003 The Optional Header (OH) marking is removed from . 12004 Large File Summit extensions are added. 12005 Issue 6 12006 Extensions beyond the ISO C standard are now marked. 12007 The following new requirements on POSIX implementations derive from alignment with the 12008 Single UNIX Specification: 12009 * The [EIO] and [EOVERFLOW] mandatory error conditions are added. 12010 * The [ENOMEM], [ENXIO], and [EILSEQ] optional error conditions are added. System Interfaces, Issue 6 865 fgetws( ) System Interfaces 12011 NAME 12012 fgetws - get a wide-character string from a stream 12013 SYNOPSIS 12014 #include 12015 #include 12016 wchar_t *fgetws(wchar_t *restrict ws, int n, | 12017 FILE *restrict stream); | 12018 DESCRIPTION | 12019 CX The functionality described on this reference page is aligned with the ISO C standard. Any 12020 conflict between the requirements described here and the ISO C standard is unintentional. This 12021 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 12022 The fgetws( ) function shall read characters from the stream, convert these to the corresponding 12023 wide-character codes, place them in the wchar_t array pointed to by ws, until n-1 characters are 12024 read, or a character is read, converted, and transferred to ws, or an end-of-file 12025 condition is encountered. The wide-character string, ws, is then terminated with a null wide- 12026 character code. 12027 If an error occurs, the resulting value of the file position indicator for the stream is 12028 indeterminate. 12029 CX The fgetws( ) function may mark the st_atime field of the file associated with stream for update. 12030 The st_atime field shall be marked for update by the first successful execution of fgetc( ), fgets( ), 12031 fgetwc( ), fgetws( ), fread( ), fscanf( ), getc( ), getchar( ), gets( ), or scanf( ) using stream that returns 12032 data not supplied by a prior call to ungetc( ) or ungetwc( ). 12033 RETURN VALUE 12034 Upon successful completion, fgetws( ) shall return ws. If the stream is at end-of-file, the end-of- 12035 file indicator for the stream shall be set and fgetws( ) shall return a null pointer. If a read error 12036 CX occurs, the error indicator for the stream shall be set, fgetws( ) shall return a null pointer, and 12037 shall set errno to indicate the error. 12038 ERRORS 12039 Refer to fgetwc( ). 12040 EXAMPLES 12041 None. 12042 APPLICATION USAGE 12043 None. 12044 RATIONALE 12045 None. 12046 FUTURE DIRECTIONS 12047 None. 12048 SEE ALSO 12049 fopen( ), fread( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , | 12050 CHANGE HISTORY 12051 First released in Issue 4. Derived from the MSE working draft. | 866 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fgetws( ) 12052 Issue 5 12053 The Optional Header (OH) marking is removed from . 12054 Issue 6 12055 Extensions beyond the ISO C standard are now marked. | 12056 The prototype for fgetws( ) is changed for alignment with the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 867 fileno( ) System Interfaces 12057 NAME 12058 fileno - map a stream pointer to a file descriptor 12059 SYNOPSIS 12060 #include 12061 int fileno(FILE *stream); 12062 DESCRIPTION 12063 The fileno( ) function shall return the integer file descriptor associated with the stream pointed to 12064 by stream. 12065 RETURN VALUE 12066 Upon successful completion, fileno( ) shall return the integer value of the file descriptor 12067 associated with stream. Otherwise, the value -1 shall be returned and errno set to indicate the 12068 error. 12069 ERRORS 12070 The fileno( ) function may fail if: 12071 [EBADF] The stream argument is not a valid stream. | 12072 EXAMPLES 12073 None. 12074 APPLICATION USAGE 12075 None. 12076 RATIONALE 12077 Without some specification of which file descriptors are associated with these streams, it is 12078 impossible for an application to set up the streams for another application it starts with fork( ) 12079 and exec. In particular, it would not be possible to write a portable version of the sh command 12080 interpreter (although there may be other constraints that would prevent that portability). 12081 FUTURE DIRECTIONS 12082 None. 12083 SEE ALSO 12084 fdopen( ), fopen( ), stdin, the Base Definitions volume of IEEE Std. 1003.1-200x, , Section | 12085 2.5.1 (on page 535) 12086 CHANGE HISTORY 12087 First released in Issue 1. Derived from Issue 1 of the SVID. | 12088 Issue 4 12089 The [EBADF] error is marked as an extension. 12090 Issue 6 12091 The following new requirements on POSIX implementations derive from alignment with the 12092 Single UNIX Specification: 12093 * The [EBADF] optional error condition is added. 868 Technical Standard (2000) (Draft July 31, 2000) System Interfaces flockfile( ) 12094 NAME 12095 flockfile, ftrylockfile, funlockfile - stdio locking functions 12096 SYNOPSIS 12097 TSF #include 12098 void flockfile(FILE *file); 12099 int ftrylockfile(FILE *file); 12100 void funlockfile(FILE *file); 12101 12102 DESCRIPTION 12103 The flockfile ( ), ftrylockfile ( ), and funlockfile ( ) functions provide for explicit application-level 12104 locking of stdio (FILE*) objects. These functions can be used by a thread to delineate a sequence 12105 of I/O statements that are executed as a unit. 12106 The flockfile ( ) function is used by a thread to acquire ownership of a (FILE*) object. 12107 The ftrylockfile ( ) function is used by a thread to acquire ownership of a (FILE*) object if the 12108 object is available; ftrylockfile ( ) is a non-blocking version of flockfile ( ). 12109 The funlockfile ( ) function is used to relinquish the ownership granted to the thread. The 12110 behavior is undefined if a thread other than the current owner calls the funlockfile ( ) function. 12111 Logically, there is a lock count associated with each (FILE*) object. This count is implicitly 12112 initialized to zero when the (FILE*) object is created. The (FILE*) object is unlocked when the 12113 count is zero. When the count is positive, a single thread owns the (FILE*) object. When the 12114 flockfile ( ) function is called, if the count is zero or if the count is positive and the caller owns the 12115 (FILE*) object, the count is incremented. Otherwise, the calling thread is suspended, waiting for 12116 the count to return to zero. Each call to funlockfile ( ) decrements the count. This allows matching 12117 calls to flockfile ( ) (or successful calls to ftrylockfile ( )) and funlockfile ( ) to be nested. 12118 All functions that reference (FILE*) objects shall behave as if they use flockfile ( ) and funlockfile ( ) 12119 internally to obtain ownership of these (FILE*) objects. 12120 RETURN VALUE 12121 None for flockfile ( ) and funlockfile ( ). The ftrylockfile ( ) function shall return zero for success and 12122 non-zero to indicate that the lock cannot be acquired. 12123 ERRORS 12124 No errors are defined. 12125 EXAMPLES 12126 None. 12127 APPLICATION USAGE 12128 Applications using these functions may be subject to priority inversion, as discussed in the Base | 12129 Definitions volume of IEEE Std. 1003.1-200x, Section 3.287, Priority Inversion. | 12130 RATIONALE 12131 The flockfile ( ) and funlockfile ( ) functions provide an orthogonal mutual exclusion lock for each 12132 FILE. The ftrylockfile ( ) function provides a non-blocking attempt to acquire a file lock, 12133 analogous to pthread_mutex_trylock( ). 12134 These locks behave as if they are the same as those used internally by stdio for thread-safety. 12135 This both provides thread-safety of these functions without requiring a second level of internal 12136 locking and allows functions in stdio to be implemented in terms of other stdio functions. 12137 Application writers and implementors should be aware that there are potential deadlock 12138 problems on FILE objects. For example, the line-buffered flushing semantics of stdio (requested System Interfaces, Issue 6 869 flockfile( ) System Interfaces 12139 via {_IOLBF}) require that certain input operations sometimes cause the buffered contents of | 12140 implementation-defined line-buffered output streams to be flushed. If two threads each hold the | 12141 lock on the other's FILE, deadlock ensues. This type of deadlock can be avoided by acquiring 12142 FILE locks in a consistent order. In particular, the line-buffered output stream deadlock can 12143 typically be avoided by acquiring locks on input streams before locks on output streams if a 12144 thread would be acquiring both. 12145 In summary, threads sharing stdio streams with other threads can use flockfile ( ) and funlockfile ( ) 12146 to cause sequences of I/O performed by a single thread to be kept bundled. The only case where 12147 the use of flockfile ( ) and funlockfile ( ) is required is to provide a scope protecting uses of the 12148 *_unlocked( ) functions/macros. This moves the cost/performance tradeoff to the optimal point. 12149 FUTURE DIRECTIONS 12150 None. 12151 SEE ALSO 12152 getc_unlocked( ), putc_unlocked( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 12153 CHANGE HISTORY 12154 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 12155 Issue 6 12156 These functions are marked as part of the Thread-Safe Functions option. | 870 Technical Standard (2000) (Draft July 31, 2000) System Interfaces floor( ) 12157 NAME 12158 floor, floorf, floorl - floor function | 12159 SYNOPSIS 12160 #include 12161 double floor(double x); 12162 float floorf(float x); | 12163 long double floorl(long double x); | 12164 DESCRIPTION | 12165 CX The functionality described on this reference page is aligned with the ISO C standard. Any 12166 conflict between the requirements described here and the ISO C standard is unintentional. This 12167 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 12168 These functions shall compute the largest integral value not greater than x. | 12169 An application wishing to check for error situations should set errno to 0 before calling floor( ). If 12170 errno is non-zero on return, or the return value is NaN, an error has occurred. 12171 RETURN VALUE 12172 Upon successful completion, these functions shall return the largest integral value not greater | 12173 than x, expressed as a double. | 12174 XSI If x is NaN, NaN shall be returned and errno may be set to [EDOM]. | 12175 If the correct value would cause overflow, -HUGE_VAL shall be returned and errno set to 12176 [ERANGE]. | 12177 XSI If x is ±Inf or ±0, the value of x shall be returned. 12178 ERRORS 12179 These functions shall fail if: | 12180 [ERANGE] The result would cause an overflow. | 12181 These functions may fail if: | 12182 XSI [EDOM] The value of x is NaN. | 12183 XSI No other errors shall occur. 12184 EXAMPLES 12185 None. 12186 APPLICATION USAGE 12187 The integral value returned by floor( ) as a double might not be expressible as an int or long. The | 12188 return value should be tested before assigning it to an integer type to avoid the undefined results 12189 of an integer overflow. 12190 The floor( ) function can only overflow when the floating point representation has 12191 DBL_MANT_DIG > DBL_MAX_EXP. 12192 RATIONALE 12193 None. 12194 FUTURE DIRECTIONS 12195 None. System Interfaces, Issue 6 871 floor( ) System Interfaces 12196 SEE ALSO 12197 ceil( ), isnan( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 12198 CHANGE HISTORY 12199 First released in Issue 1. Derived from Issue 1 of the SVID. | 12200 Issue 4 12201 References to matherr( ) are removed. 12202 The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 12203 ISO C standard and to rationalize handling in the mathematics functions. 12204 The word long has been replaced with the words long in the APPLICATION USAGE section. | 12205 The return value specified for [EDOM] is marked as an extension. 12206 Issue 5 12207 The DESCRIPTION is updated to indicate how an application should check for an error. This 12208 text was previously published in the APPLICATION USAGE section. | 12209 Issue 6 || 12210 The floorf( ) and floorl( ) functions are added for alignment with the ISO/IEC 9899: 1999 standard. | 872 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fma( ) 12211 NAME | 12212 fma, fmaf, fmal - floating-point multiply-add | 12213 SYNOPSIS | 12214 #include | 12215 double fma(double x, double y, double z); | 12216 float fmaf(float x, float y, float z); | 12217 long double fmal(long double x, long double y, long double z); | 12218 DESCRIPTION | 12219 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 12220 conflict between the requirements described here and the ISO C standard is unintentional. This | 12221 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 12222 These functions shall compute (x * y) + z, rounded as one ternary operation: they shall compute | 12223 the value (as if) to infinite precision and round once to the result format, according to the | 12224 rounding mode characterized by the value of FLT_ROUNDS. | 12225 An application wishing to check for error situations should set errno to 0 before calling these | 12226 functions. If errno is non-zero on return, or the return value is NaN, an error has occurred. | 12227 RETURN VALUE | 12228 Upon successful completion, these functions shall return (x * y) + z, rounded as one ternary | 12229 operation. | 12230 If x, y, or z is NaN, NaN shall be returned and errno may be set to [EDOM]. | 12231 ERRORS | 12232 These functions may fail if: | 12233 [EDOM] The value of x, y, or z is NaN. | 12234 EXAMPLES | 12235 None. | 12236 APPLICATION USAGE | 12237 None. | 12238 RATIONALE | 12239 In many cases, clever use of floating (fused) multiply-add leads to much improved code; but its | 12240 unexpected use by the compiler can undermine carefully written code. The FP_CONTRACT | 12241 macro can be used to disallow use of floating multiply-add; and the fma( ) function guarantees | 12242 its use where desired. Many current machines provide hardware floating multiply-add | 12243 instructions; software implementation can be used for others. | 12244 FUTURE DIRECTIONS | 12245 None. | 12246 SEE ALSO | 12247 The Base Definitions volume of IEEE Std. 1003.1-200x, | 12248 CHANGE HISTORY || 12249 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 873 fmax( ) System Interfaces 12250 NAME | 12251 fmax, fmaxf, fmaxl - determine maximum numeric value of two floating-point numbers | 12252 SYNOPSIS | 12253 #include | 12254 double fmax(double x, double y); | 12255 float fmaxf(float x, float y); | 12256 long double fmaxl(long double x, long double y); | 12257 DESCRIPTION | 12258 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 12259 conflict between the requirements described here and the ISO C standard is unintentional. This | 12260 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 12261 These functions shall determine the maximum numeric value of their arguments. NaN | 12262 arguments shall be treated as missing data: if one argument is a NaN and the other numeric, | 12263 then the fmax( ), fmaxf( ), and fmaxl( ) functions shall choose the numeric value. | 12264 An application wishing to check for error situations should set errno to 0 before calling these | 12265 functions. If errno is non-zero on return, or the return value is NaN, an error has occurred. | 12266 RETURN VALUE | 12267 Upon successful completion, these functions shall return the maximum numeric value of their | 12268 arguments. | 12269 If x and y are NaN, NaN shall be returned and errno may be set to [EDOM]. | 12270 ERRORS | 12271 These functions may fail if: | 12272 [EDOM] The value of x and y is NaN. | 12273 EXAMPLES | 12274 None. | 12275 APPLICATION USAGE | 12276 None. | 12277 RATIONALE | 12278 None. | 12279 FUTURE DIRECTIONS | 12280 None. | 12281 SEE ALSO | 12282 fdim( ), fmin( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 12283 CHANGE HISTORY || 12284 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | 874 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fmin( ) 12285 NAME | 12286 fmin, fminf, fminl - determine minimum numeric value of two floating-point numbers | 12287 SYNOPSIS | 12288 #include | 12289 double fmin(double x, double y); | 12290 float fminf(float x, float y); | 12291 long double fminl(long double x, long double y); | 12292 DESCRIPTION | 12293 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 12294 conflict between the requirements described here and the ISO C standard is unintentional. This | 12295 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 12296 These functions shall determine the minimum numeric value of their arguments. NaN | 12297 arguments shall be treated as missing data: if one argument is a NaN and the other numeric, | 12298 then these functions shall choose the numeric value. | 12299 An application wishing to check for error situations should set errno to 0 before calling these | 12300 functions. If errno is non-zero on return, or the return value is NaN, an error has occurred. | 12301 RETURN VALUE | 12302 Upon successful completion, these functions shall return the minimum numeric value of their | 12303 arguments. | 12304 If x and y are NaN, NaN shall be returned and errno may be set to [EDOM]. | 12305 ERRORS | 12306 These functions may fail if: | 12307 [EDOM] The value of x and y is NaN. | 12308 EXAMPLES | 12309 None. | 12310 APPLICATION USAGE | 12311 None. | 12312 RATIONALE | 12313 None. | 12314 FUTURE DIRECTIONS | 12315 None. | 12316 SEE ALSO | 12317 fdim( ), fmax( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 12318 CHANGE HISTORY || 12319 First released in Issue 6. Derived from ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 875 fmod( ) System Interfaces 12320 NAME 12321 fmod, fmodf, fmodl - floating-point remainder value function | 12322 SYNOPSIS 12323 #include 12324 double fmod(double x, double y); 12325 float fmodf(float x, float y); | 12326 long double fmodl(long double x, long double y); | 12327 DESCRIPTION | 12328 CX The functionality described on this reference page is aligned with the ISO C standard. Any 12329 conflict between the requirements described here and the ISO C standard is unintentional. This 12330 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 12331 These functions shall return the floating-point remainder of the division of x by y. | 12332 An application wishing to check for error situations should set errno to 0 before calling fmod( ). If 12333 errno is non-zero on return, or the return value is NaN, an error has occurred. 12334 RETURN VALUE 12335 These functions shall return the value x-i*y, for some integer i such that, if y is non-zero, the | 12336 result has the same sign as x and magnitude less than the magnitude of y. 12337 XSI If x or y is NaN, NaN shall be returned and errno may be set to [EDOM]. | 12338 XSI If y is 0, NaN shall be returnedand errno set to [EDOM], or 0 shall be returned and errno may be 12339 set to [EDOM]. 12340 XSI If x is ±Inf, either 0 shall be returned and errno set to [EDOM], or NaN shall be returned and errno 12341 may be set to [EDOM]. 12342 If y is non-zero, fmod(±0,y) shall return the value of x. If x is not ±Inf, fmod(x,±Inf) shall return 12343 the value of x. 12344 If the result underflows, 0 shall be returned and errno may be set to [ERANGE]. | 12345 ERRORS 12346 These functions may fail if: | 12347 XSI [EDOM] One or both of the arguments is NaN, or y is 0, or x is ±Inf. | 12348 [ERANGE] The result underflows | 12349 XSI No other errors shall occur. 12350 EXAMPLES 12351 None. 12352 APPLICATION USAGE 12353 Portable applications should not call fmod( ) with y equal to 0, because the result is | 12354 implementation-defined. The application should verify y is non-zero before calling fmod( ). | 12355 RATIONALE 12356 None. 12357 FUTURE DIRECTIONS 12358 None. 876 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fmod( ) 12359 SEE ALSO 12360 isnan( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 12361 CHANGE HISTORY 12362 First released in Issue 1. Derived from Issue 1 of the SVID. | 12363 Issue 4 12364 References to matherr( ) are removed. 12365 The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 12366 ISO C standard and to rationalize error handling in the mathematics functions. 12367 The return value specified for [EDOM] is marked as an extension. 12368 Issue 5 12369 The DESCRIPTION is updated to indicate how an application should check for an error. This 12370 text was previously published in the APPLICATION USAGE section. | 12371 Issue 6 | 12372 The fmodf( ) and fmodl( ) functions are added for alignment with the ISO/IEC 9899: 1999 | 12373 standard. | System Interfaces, Issue 6 877 fmtmsg( ) System Interfaces 12374 NAME 12375 fmtmsg - display a message in the specified format on standard error and/or a system console 12376 SYNOPSIS 12377 XSI #include 12378 int fmtmsg(long classification, const char *label, int severity, 12379 const char *text, const char *action, const char *tag); 12380 12381 DESCRIPTION 12382 The fmtmsg( ) function can be used to display messages in a specified format instead of the 12383 traditional printf( ) function. 12384 Based on a message's classification component, fmtmsg( ) writes a formatted message either to 12385 standard error, to the console, or to both. 12386 A formatted message consists of up to five components as defined below. The component 12387 classification is not part of a message displayed to the user, but defines the source of the message 12388 and directs the display of the formatted message. 12389 classification Contains identifiers from the following groups of major classifications and 12390 subclassifications. Any one identifier from a subclass may be used in 12391 combination with a single identifier from a different subclass. Two or more 12392 identifiers from the same subclass should not be used together, with the 12393 exception of identifiers from the display subclass. (Both display subclass 12394 identifiers may be used so that messages can be displayed to both standard 12395 error and the system console). 12396 Major Classifications 12397 Identifies the source of the condition. Identifiers are: MM_HARD 12398 (hardware), MM_SOFT (software), and MM_FIRM (firmware). 12399 Message Source Subclassifications 12400 Identifies the type of software in which the problem is detected. 12401 Identifiers are: MM_APPL (application), MM_UTIL (utility), and 12402 MM_OPSYS (operating system). 12403 Display Subclassifications 12404 Indicates where the message is to be displayed. Identifiers are: 12405 MM_PRINT to display the message on the standard error stream, 12406 MM_CONSOLE to display the message on the system console. One or 12407 both identifiers may be used. 12408 Status Subclassifications 12409 Indicates whether the application can recover from the condition. 12410 Identifiers are: MM_RECOVER (recoverable) and MM_NRECOV (non- 12411 recoverable). 12412 An additional identifier, MM_NULLMC, indicates that no classification 12413 component is supplied for the message. 12414 label Identifies the source of the message. The format is two fields separated by a 12415 colon. The first field is up to 10 bytes, the second is up to 14 bytes. 12416 severity Indicates the seriousness of the condition. Identifiers for the levels of severity 12417 are: 878 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fmtmsg( ) 12418 MM_HALT Indicates that the application has encountered a severe fault 12419 and is halting. Produces the string "HALT". 12420 MM_ERROR Indicates that the application has detected a fault. Produces 12421 the string "ERROR". | 12422 MM_WARNING Indicates a condition that is out of the ordinary, that might 12423 be a problem, and should be watched. Produces the string 12424 "WARNING". 12425 MM_INFO Provides information about a condition that is not in error. 12426 Produces the string "INFO". 12427 MM_NOSEV Indicates that no severity level is supplied for the message. 12428 text Describes the error condition that produced the message. The character string 12429 is not limited to a specific size. If the character string is empty, then the text 12430 produced is unspecified. 12431 action Describes the first step to be taken in the error-recovery process. The fmtmsg( ) 12432 function precedes the action string with the prefix: "TO FIX:". The action 12433 string is not limited to a specific size. 12434 tag An identifier that references on-line documentation for the message. 12435 Suggested usage is that tag includes the label and a unique identifying number. 12436 A sample tag is "XSI:cat:146". 12437 The MSGVERB environment variable (for message verbosity) tells fmtmsg( ) which message 12438 components it is to select when writing messages to standard error. The value of MSGVERB is a 12439 colon-separated list of optional keywords. Valid keywords are: label, severity, text, action, and tag. If 12440 MSGVERB contains a keyword for a component and the component's value is not the 12441 component's null value, fmtmsg( ) includes that component in the message when writing the 12442 message to standard error. If MSGVERB does not include a keyword for a message component, 12443 that component is not included in the display of the message. The keywords may appear in any 12444 order. If MSGVERB is not defined, if its value is the null string, if its value is not of the correct 12445 format, or if it contains keywords other than the valid ones listed above, fmtmsg( ) selects all 12446 components. 12447 MSGVERB affects only which components are selected for display to standard error. All 12448 message components are included in console messages. 12449 RETURN VALUE 12450 The fmtmsg( ) function shall return one of the following values: 12451 MM_OK The function succeeded. 12452 MM_NOTOK The function failed completely. 12453 MM_NOMSG The function was unable to generate a message on standard error, but 12454 otherwise succeeded. 12455 MM_NOCON The function was unable to generate a console message, but otherwise 12456 succeeded. 12457 ERRORS 12458 None. System Interfaces, Issue 6 879 fmtmsg( ) System Interfaces 12459 EXAMPLES 12460 1. The following example of fmtmsg( ): 12461 fmtmsg(MM_PRINT, "XSI:cat", MM_ERROR, "illegal option", 12462 "refer to cat in user's reference manual", "XSI:cat:001") 12463 produces a complete message in the specified message format: 12464 XSI:cat: ERROR: illegal option 12465 TO FIX: refer to cat in user's reference manual XSI:cat:001 12466 2. When the environment variable MSGVERB is set as follows: 12467 MSGVERB=severity:text:action 12468 and Example 1 is used, fmtmsg( ) produces: 12469 ERROR: illegal option 12470 TO FIX: refer to cat in user's reference manual 12471 APPLICATION USAGE 12472 One or more message components may be systematically omitted from messages generated by 12473 an application by using the null value of the argument for that component. 12474 RATIONALE 12475 None. 12476 FUTURE DIRECTIONS 12477 None. 12478 SEE ALSO 12479 printf( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 12480 CHANGE HISTORY 12481 First released in Issue 4, Version 2. 12482 Issue 5 12483 Moved from X/OPEN UNIX extension to BASE. 880 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fnmatch( ) 12484 NAME 12485 fnmatch - match a file name or a path name 12486 SYNOPSIS 12487 #include 12488 int fnmatch(const char *pattern, const char *string, int flags); 12489 DESCRIPTION 12490 The fnmatch( ) function shall match patterns as described in the Shell and Utilities volume of | 12491 IEEE Std. 1003.1-200x, Section 2.14.1, Patterns Matching a Single Character, and Section 2.14.2, | 12492 Patterns Matching Multiple Characters. It checks the string specified by the string argument to | 12493 see if it matches the pattern specified by the pattern argument. 12494 The flags argument modifies the interpretation of pattern and string. It is the bitwise-inclusive OR 12495 of zero or more of the flags defined in . If the FNM_PATHNAME flag is set in flags, 12496 then a slash character ('/') in string shall be explicitly matched by a slash in pattern; it shall not 12497 be matched by either the asterisk or question-mark special characters, nor by a bracket 12498 expression. If the FNM_PATHNAME flag is not set, the slash character is treated as an ordinary 12499 character. 12500 If FNM_NOESCAPE is not set in flags, a backslash character ('\') in pattern followed by any 12501 other character shall match that second character in string. In particular, "\\" shall match a 12502 backslash in string. If FNM_NOESCAPE is set, a backslash character shall be treated as an 12503 ordinary character. 12504 If FNM_PERIOD is set in flags, then a leading period ('.') in string shall match a period in 12505 pattern; as described by rule 2 in the Shell and Utilities volume of IEEE Std. 1003.1-200x, Section | 12506 2.14.3, Patterns Used for File Name Expansion where the location of ``leading'' is indicated by | 12507 the value of FNM_PATHNAME: 12508 * If FNM_PATHNAME is set, a period is ``leading'' if it is the first character in string or if it 12509 immediately follows a slash. 12510 * If FNM_PATHNAME is not set, a period is ``leading'' only if it is the first character of string. 12511 If FNM_PERIOD is not set, then no special restrictions are placed on matching a period. 12512 RETURN VALUE 12513 If string matches the pattern specified by pattern, then fnmatch( ) shall return 0. If there is no 12514 match, fnmatch( ) shall return FNM_NOMATCH, which is defined in . If an error 12515 occurs, fnmatch( ) shall return another non-zero value. 12516 ERRORS 12517 No errors are defined. 12518 EXAMPLES 12519 None. 12520 APPLICATION USAGE 12521 The fnmatch( ) function has two major uses. It could be used by an application or utility that 12522 needs to read a directory and apply a pattern against each entry. The find utility is an example of 12523 this. It can also be used by the pax utility to process its pattern operands, or by applications that 12524 need to match strings in a similar manner. 12525 The name fnmatch( ) is intended to imply file name match, rather than path name match. The 12526 default action of this function is to match file names, rather than path names, since it gives no 12527 special significance to the slash character. With the FNM_PATHNAME flag, fnmatch( ) does 12528 match path names, but without tilde expansion, parameter expansion, or special treatment for a System Interfaces, Issue 6 881 fnmatch( ) System Interfaces 12529 period at the beginning of a file name. 12530 RATIONALE 12531 This function replaced the REG_FILENAME flag of regcomp( ) in early proposals of this volume 12532 of IEEE Std. 1003.1-200x. It provides virtually the same functionality as the regcomp( ) and 12533 regexec( ) functions using the REG_FILENAME and REG_FSLASH flags (the REG_FSLASH flag 12534 was proposed for regcomp( ), and would have had the opposite effect from FNM_PATHNAME), 12535 but with a simpler function and less system overhead. 12536 FUTURE DIRECTIONS 12537 None. 12538 SEE ALSO 12539 glob( ), wordexp( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , the Shell | 12540 and Utilities volume of IEEE Std. 1003.1-200x | 12541 CHANGE HISTORY 12542 First released in Issue 4. Derived from the ISO POSIX-2 standard. | 12543 Issue 5 12544 Moved from POSIX2 C-language Binding to BASE. 882 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fopen( ) 12545 NAME 12546 fopen - open a stream 12547 SYNOPSIS 12548 #include 12549 FILE *fopen(const char *restrict filename, const char *restrict mode); | 12550 DESCRIPTION | 12551 CX The functionality described on this reference page is aligned with the ISO C standard. Any 12552 conflict between the requirements described here and the ISO C standard is unintentional. This 12553 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 12554 The fopen( ) function shall open the file whose path name is the string pointed to by filename, and 12555 associates a stream with it. 12556 The argument mode points to a string. If the string is one of the following, the file is open in the | 12557 indicated mode. Otherwise, the behavior is undefined. | 12558 r or rb Open file for reading. 12559 w or wb Truncate to zero length or create file for writing. 12560 a or ab Append; open or create file for writing at end-of-file. 12561 r+ or rb+ or r+b Open file for update (reading and writing). 12562 w+ or wb+ or w+b Truncate to zero length or create file for update. 12563 a+ or ab+ or a+b Append; open or create file for update, writing at end-of-file. 12564 CX The character 'b' has no effect, but is allowed for ISO C standard conformance. Opening a file 12565 with read mode (r as the first character in the mode argument) shall fail if the file does not exist or 12566 cannot be read. 12567 Opening a file with append mode (a as the first character in the mode argument) shall cause all 12568 subsequent writes to the file to be forced to the then current end-of-file, regardless of intervening 12569 calls to fseek( ). 12570 When a file is opened with update mode ('+' as the second or third character in the mode 12571 argument), both input and output may be performed on the associated stream. However, the 12572 application shall ensure that output is not directly followed by input without an intervening call 12573 to fflush( ) or to a file positioning function (fseek( ), fsetpos( ), or rewind( )), and input is not directly 12574 followed by output without an intervening call to a file positioning function, unless the input 12575 operation encounters end-of-file. 12576 When opened, a stream is fully buffered if and only if it can be determined not to refer to an 12577 interactive device. The error and end-of-file indicators for the stream shall be cleared. 12578 CX If mode is w, a, w+, or a+, and the file did not previously exist, upon successful completion, 12579 fopen( ) function shall mark for update the st_atime, st_ctime, and st_mtime fields of the file and 12580 the st_ctime and st_mtime fields of the parent directory. 12581 If mode is w or w+ and the file did previously exist, upon successful completion, fopen( ) shall 12582 mark for update the st_ctime and st_mtime fields of the file. The fopen( ) function shall allocate a 12583 file descriptor as open( ) does. 12584 XSI After a successful call to the fopen( ) function, the orientation of the stream shall be cleared, the 12585 encoding rule shall be cleared, and the associated mbstate_t object shall be set to describe an 12586 initial conversion state. System Interfaces, Issue 6 883 fopen( ) System Interfaces 12587 The largest value that can be represented correctly in an object of type off_t shall be established 12588 as the offset maximum in the open file description. 12589 RETURN VALUE 12590 Upon successful completion, fopen( ) shall return a pointer to the object controlling the stream. 12591 CX Otherwise, a null pointer shall be returned, and errno shall be set to indicate the error. 12592 ERRORS 12593 The fopen( ) function shall fail if: 12594 CX [EACCES] Search permission is denied on a component of the path prefix, or the file | 12595 exists and the permissions specified by mode are denied, or the file does not 12596 exist and write permission is denied for the parent directory of the file to be 12597 created. 12598 CX [EINTR] A signal was caught during fopen( ). | 12599 CX [EISDIR] The named file is a directory and mode requires write access. | 12600 CX [ELOOP] A loop exists in symbolic links encountered during resolution of the path | 12601 argument. | 12602 CX [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. | 12603 CX [ENAMETOOLONG] | 12604 The length of the filename argument exceeds {PATH_MAX} or a path name | 12605 component is longer than {NAME_MAX}. | 12606 CX [ENFILE] The maximum allowable number of files is currently open in the system. | 12607 CX [ENOENT] A component of filename does not name an existing file or filename is an empty | 12608 string. 12609 CX [ENOSPC] The directory or file system that would contain the new file cannot be | 12610 expanded, the file does not exist, and it was to be created. 12611 CX [ENOTDIR] A component of the path prefix is not a directory. | 12612 CX [ENXIO] The named file is a character special or block special file, and the device | 12613 associated with this special file does not exist. 12614 CX [EOVERFLOW] The named file is a regular file and the size of the file cannot be represented | 12615 correctly in an object of type off_t. 12616 CX [EROFS] The named file resides on a read-only file system and mode requires write | 12617 access. 12618 The fopen( ) function may fail if: 12619 CX [EINVAL] The value of the mode argument is not valid. | 12620 CX [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during | 12621 resolution of the path argument. | 12622 CX [EMFILE] {FOPEN_MAX} streams are currently open in the calling process. | 12623 CX [EMFILE] {STREAM_MAX} streams are currently open in the calling process. | 12624 CX [ENAMETOOLONG] | 12625 Path name resolution of a symbolic link produced an intermediate result 12626 whose length exceeds {PATH_MAX}. 884 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fopen( ) 12627 CX [ENOMEM] Insufficient storage space is available. | 12628 CX [ETXTBSY] The file is a pure procedure (shared text) file that is being executed and mode | 12629 requires write access. 12630 EXAMPLES 12631 Opening a File 12632 The following example tries to open the file named file for reading. The fopen( ) function returns | 12633 a file pointer that is used in subsequent fgets( ) and fclose( ) calls. If the program cannot open the | 12634 file, it just ignores it. 12635 #include 12636 ... 12637 FILE *fp; 12638 ... 12639 void rgrep(const char *file) 12640 { 12641 ... 12642 if ((fp = fopen(file, "r")) == NULL) 12643 return; 12644 ... 12645 } 12646 APPLICATION USAGE 12647 None. 12648 RATIONALE 12649 None. 12650 FUTURE DIRECTIONS 12651 None. 12652 SEE ALSO 12653 fclose( ), fdopen( ), freopen( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 12654 CHANGE HISTORY 12655 First released in Issue 1. Derived from Issue 1 of the SVID. | 12656 Issue 4 12657 In the DESCRIPTION, the descriptions of input and output operations on update streams are 12658 changed to be requirements on the application. 12659 The [EMFILE] error is added to the ERRORS section, and all the optional errors are marked as 12660 extensions. 12661 The following changes are incorporated for alignment with the ISO C standard: 12662 * The type of arguments filename and mode are changed from char* to const char*. 12663 * In the DESCRIPTION, the use and settings of the mode argument are changed to support 12664 binary streams, and setpos( ) is added to the list of file positioning functions. 12665 The following change is incorporated for alignment with the FIPS requirements: 12666 * In the ERRORS section, the condition whereby [ENAMETOOLONG] is returned if a path 12667 name component is larger that {NAME_MAX} is now defined as mandatory and marked as 12668 an extension. System Interfaces, Issue 6 885 fopen( ) System Interfaces 12669 Issue 4, Version 2 12670 The ERRORS section is updated for X/OPEN UNIX conformance as follows: 12671 * It states that [ELOOP] is returned if too many symbolic links are encountered during path 12672 name resolution. 12673 * A second [ENAMETOOLONG] condition is defined that may report excessive length of an 12674 intermediate result of path name resolution of a symbolic link. 12675 Issue 5 12676 Large File Summit extensions are added. 12677 Issue 6 12678 Extensions beyond the ISO C standard are now marked. 12679 The following changes are made for alignment with the ISO POSIX-1: 1996 standard: 12680 * The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. 12681 This is since behavior may vary from one file system to another. 12682 The following new requirements on POSIX implementations derive from alignment with the 12683 Single UNIX Specification: 12684 * In the DESCRIPTION, text is added to indicate setting of the offset maximum in the open file 12685 description. This change is to support large files. 12686 * In the ERRORS section, the [EOVERFLOW] condition is added. This change is to support 12687 large files. 12688 * The [ELOOP] mandatory error condition is added. 12689 * The [EINVAL], [EMFILE], [ENAMETOOLONG], [ENOMEM], and [ETXTBSY] optional error 12690 conditions are added. 12691 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. | 12692 The following changes are made for alignment with the ISO/IEC 9899: 1999 standard: | 12693 * The prototype for fopen( ) is updated. | 12694 * The DESCRIPTION is updated to note that if the argument mode points to a string other than | 12695 those listed, then the behavior is undefined. | 12696 The wording of the mandatory [ELOOP] error condition is updated, and a second optional | 12697 [ELOOP] error condition is added. | 886 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fork( ) 12698 NAME 12699 fork - create a new process 12700 SYNOPSIS 12701 #include 12702 pid_t fork(void); 12703 DESCRIPTION 12704 The fork( ) function creates a new process. The new process (child process) shall be an exact copy 12705 of the calling process (parent process) except as detailed below: 12706 * The child process has a unique process ID. 12707 * The child process ID also does not match any active process group ID. 12708 * The child process has a different parent process ID (that is, the process ID of the parent 12709 process). 12710 * The child process has its own copy of the parent's file descriptors. Each of the child's file 12711 descriptors refers to the same open file description with the corresponding file descriptor of 12712 the parent. 12713 * The child process has its own copy of the parent's open directory streams. Each open 12714 directory stream in the child process may share directory stream positioning with the 12715 corresponding directory stream of the parent. 12716 XSI * The child process may have its own copy of the parent's message catalog descriptors. 12717 * The child process' values of tms_utime, tms_stime, tms_cutime, and tms_cstime are set to 0. 12718 * The time left until an alarm clock signal is reset to zero, and the alarm, if any, is canceled; see 12719 alarm( ). 12720 XSI * All semadj values are cleared. 12721 * File locks set by the parent process are not inherited by the child process. 12722 * The set of signals pending for the child process is initialized to the empty set. 12723 XSI * Interval timers are reset in the child process. 12724 SEM * Any semaphores that are open in the parent process shall also be open in the child process. 12725 ML * The child process does not inherit any address space memory locks established by the parent 12726 process via calls to mlockall( ) or mlock( ). 12727 MF|SHM * Memory mappings created in the parent are retained in the child process. MAP_PRIVATE 12728 mappings inherited from the parent shall also be MAP_PRIVATE mappings in the child, and 12729 any modifications to the data in these mappings made by the parent prior to calling fork( ) 12730 shall be visible to the child. Any modifications to the data in MAP_PRIVATE mappings made 12731 by the parent after fork( ) returns shall be visible only to the parent. Modifications to the data 12732 in MAP_PRIVATE mappings made by the child shall be visible only to the child. 12733 PS * For the SCHED_FIFO and SCHED_RR scheduling policies, the child process shall inherit the 12734 policy and priority settings of the parent process during a fork( ) function. For other 12735 scheduling policies, the policy and priority settings on fork( ) are implementation-defined. | 12736 TMR * Per-process timers created by the parent are not inherited by the child process. 12737 MSG * The child process has its own copy of the message queue descriptors of the parent. Each of 12738 the message descriptors of the child refers to the same open message queue description as 12739 the corresponding message descriptor of the parent. System Interfaces, Issue 6 887 fork( ) System Interfaces 12740 AIO * No asynchronous input or asynchronous output operations are inherited by the child 12741 process. 12742 * A process is created with a single thread. If a multi-threaded process calls fork( ), the new 12743 process contains a replica of the calling thread and its entire address space, possibly 12744 including the states of mutexes and other resources. Consequently, to avoid errors, the child 12745 process may only execute async-signal-safe operations until such time as one of the exec 12746 THR functions is called. Fork handlers may be established by means of the pthread_atfork( ) 12747 function in order to maintain application invariants across fork( ) calls. | 12748 TRC TRI * If the Trace option and the Trace Inherit option are both supported: | 12749 If the calling process was being traced in a trace stream that had its inheritance policy set to | 12750 POSIX_TRACE_INHERITED, the child process shall be traced into that trace stream, and the | 12751 child process shall inherit the parent's mapping of trace event names to trace event type | 12752 identifiers. If the trace stream in which the calling process was being traced had its | 12753 inheritance policy set to POSIX_TRACE_CLOSE_FOR_CHILD, the child process shall not be | 12754 traced into that trace stream. The inheritance policy is set by a call to the | 12755 posix_trace_attr_setinherited( ) function. | 12756 TRC * If the Trace option is supported, but the Trace Inherit option is not supported: | 12757 The child process shall not be traced into any of the trace streams of its parent process. | 12758 * If the Trace option is supported, the child process of a trace controller process shall not | 12759 control the trace streams controlled by its parent process. | 12760 CPT The initial value of the CPU-time clock of the child process shall be set to zero. 12761 TCT The initial value of the CPU-time clock of the single thread of the child process shall be set to 12762 zero. 12763 Notes to Reviewers 12764 This section with side shading will not appear in the final copy. - Ed. 12765 Check this text is correct after new addenda are rolled in. (Ref D1, XSH, ERN 126) 12766 For process characteristics not defined by this volume of IEEE Std. 1003.1-200x, their inheritance 12767 is not defined by this volume of IEEE Std. 1003.1-200x. Process characteristics defined by this 12768 volume of IEEE Std. 1003.1-200x have their inheritance explicitly defined. 12769 After fork( ), both the parent and the child processes are capable of executing independently 12770 before either one terminates. 12771 RETURN VALUE 12772 Upon successful completion, fork( ) shall return 0 to the child process and shall return the 12773 process ID of the child process to the parent process. Both processes shall continue to execute 12774 from the fork( ) function. Otherwise, -1 shall be returned to the parent process, no child process 12775 shall be created, and errno shall be set to indicate the error. 12776 ERRORS 12777 The fork( ) function shall fail if: 12778 [EAGAIN] The system lacked the necessary resources to create another process, or the | 12779 system-imposed limit on the total number of processes under execution 12780 system-wide or by a single user {CHILD_MAX} would be exceeded. 12781 The fork( ) function may fail if: 888 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fork( ) 12782 [ENOMEM] Insufficient storage space is available. | 12783 EXAMPLES 12784 None. 12785 APPLICATION USAGE 12786 None. 12787 RATIONALE 12788 Many historical implementations have timing windows where a signal sent to a process group 12789 (for example, an interactive SIGINT) just prior to or during execution of fork( ) is delivered to the 12790 parent following the fork( ) but not to the child because the fork( ) code clears the child's set of 12791 pending signals. This volume of IEEE Std. 1003.1-200x does not require, or even permit, this 12792 behavior. However, it is pragmatic to expect that problems of this nature may continue to exist 12793 in implementations that appear to conform to this volume of IEEE Std. 1003.1-200x and pass 12794 available verification suites. This behavior is only a consequence of the implementation failing to 12795 make the interval between signal generation and delivery totally invisible. From the 12796 application's perspective, a fork( ) call should appear atomic. A signal that is generated prior to 12797 the fork( ) should be delivered prior to the fork( ). A signal sent to the process group after the 12798 fork( ) should be delivered to both parent and child. The implementation may actually initialize 12799 internal data structures corresponding to the child's set of pending signals to include signals 12800 sent to the process group during the fork( ). Since the fork( ) call can be considered as atomic 12801 from the application's perspective, the set would be initialized as empty and such signals would 12802 have arrived after the fork( ); see also . 12803 One approach that has been suggested to address the problem of signal inheritance across fork( ) 12804 is to add an [EINTR] error, which would be returned when a signal is detected during the call. | 12805 While this is preferable to losing signals, it was not considered an optimal solution. Although it 12806 is not recommended for this purpose, such an error would be an allowable extension for an 12807 implementation. 12808 The [ENOMEM] error value is reserved for those implementations that detect and distinguish | 12809 such a condition. This condition occurs when an implementation detects that there is not enough 12810 memory to create the process. This is intended to be returned when [EAGAIN] is inappropriate | 12811 because there can never be enough memory (either primary or secondary storage) to perform the 12812 operation. Because fork( ) duplicates an existing process, this must be a condition where there is 12813 sufficient memory for one such process, but not for two. Many historical implementations 12814 actually return [ENOMEM] due to temporary lack of memory, a case that is not generally | 12815 distinct from [EAGAIN] from the perspective of a portable application. 12816 Part of the reason for including the optional error [ENOMEM] is because the SVID specifies it 12817 and it should be reserved for the error condition specified there. The condition is not applicable 12818 on many implementations. 12819 IEEE Std. 1003.1-1988 neglected to require concurrent execution of the parent and child of fork( ). | 12820 A system that single-threads processes was clearly not intended and is considered an 12821 unacceptable ``toy implementation'' of this volume of IEEE Std. 1003.1-200x. The only objection 12822 anticipated to the phrase ``executing independently'' is testability, but this assertion should be 12823 testable. Such tests require that both the parent and child can block on a detectable action of the 12824 other, such as a write to a pipe or a signal. An interactive exchange of such actions should be 12825 possible for the system to conform to the intent of this volume of IEEE Std. 1003.1-200x. 12826 The [EAGAIN] error exists to warn applications that such a condition might occur. Whether it 12827 occurs or not is not in any practical sense under the control of the application because the 12828 condition is usually a consequence of the user's use of the system, not of the application's code. 12829 Thus, no application can or should rely upon its occurrence under any circumstances, nor System Interfaces, Issue 6 889 fork( ) System Interfaces 12830 should the exact semantics of what concept of ``user'' is used be of concern to the application 12831 writer. Validation writers should be cognizant of this limitation. 12832 There are two reasons why POSIX programmers call fork( ). One reason is to create a new thread 12833 of control within the same program (which was originally only possible in POSIX by creating a 12834 new process); the other is to create a new process running a different program. In the latter case, 12835 the call to fork( ) is soon followed by a call to one of the exec functions. 12836 The general problem with making fork( ) work in a multi-threaded world is what to do with all 12837 of the threads. There are two alternatives. One is to copy all of the threads into the new process. 12838 This causes the programmer or implementation to deal with threads that are suspended on 12839 system calls or that might be about to execute system calls that should not be executed in the 12840 new process. The other alternative is to copy only the thread that calls fork( ). This creates the 12841 difficulty that the state of process-local resources is usually held in process memory. If a thread 12842 that is not calling fork( ) holds a resource, that resource is never released in the child process 12843 because the thread whose job it is to release the resource does not exist in the child process. 12844 When a programmer is writing a multi-threaded program, the first described use of fork( ), 12845 creating new threads in the same program, is provided by the pthread_create( ) function. The 12846 fork( ) function is thus used only to run new programs, and the effects of calling functions that 12847 require certain resources between the call to fork( ) and the call to an exec function are undefined. 12848 The addition of the forkall ( ) function to the standard was considered and rejected. The forkall ( ) | 12849 function lets all the threads in the parent be duplicated in the child. This essentially duplicates 12850 the state of the parent in the child. This allows threads in the child to continue processing and 12851 allows locks and the state to be preserved without explicit pthread_atfork( ) code. The calling 12852 process has to ensure that the threads processing state that is shared between the parent and 12853 child (that is, file descriptors or MAP_SHARED memory) behaves properly after forkall ( ). For 12854 example, if a thread is reading a file descriptor in the parent when forkall ( ) is called, then two 12855 threads (one in the parent and one in the child) are reading the file descriptor after the forkall ( ). 12856 If this is not desired behavior, the parent process has to synchronize with such threads before 12857 calling forkall ( ). 12858 When forkall ( ) is called, threads, other than the calling thread, that are in POSIX System 12859 Interfaces functions that can return with an [EINTR] error may have those functions return 12860 [EINTR] if the implementation cannot ensure that the function behaves correctly in the parent 12861 and child. In particular, pthread_cond_wait( ) and pthread_cond_timedwait( ) need to return in order 12862 to ensure that the condition has not changed. These functions can be awakened by a spurious 12863 condition wakeup rather than returning [EINTR]. 12864 FUTURE DIRECTIONS 12865 None. 12866 SEE ALSO 12867 alarm( ), exec, fcntl( ), posix_trace_attr_getinherited( ), posix_trace_trid_eventid_open( ), semop( ), | 12868 signal( ), times( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , | 12869 12870 CHANGE HISTORY 12871 First released in Issue 1. Derived from Issue 1 of the SVID. | 12872 Issue 4 12873 The header is now marked as optional (OH); this header need not be included on 12874 XSI-conformant systems. 12875 The following changes are incorporated for alignment with the ISO POSIX-1 standard: 890 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fork( ) 12876 * The argument list is explicitly defined as void. 12877 * Though functionally identical to Issue 3, the DESCRIPTION has been reorganized to improve 12878 clarity and to align more closely with the ISO POSIX-1 standard. 12879 * The description of the [EAGAIN] error is updated to indicate that this error can also be 12880 returned if a system lacks the resources to create another process. 12881 Issue 4, Version 2 12882 The DESCRIPTION is changed for X/OPEN UNIX conformance to identify that interval timers 12883 are reset in the child process. 12884 Issue 5 12885 The DESCRIPTION is changed for alignment with the POSIX Realtime Extension and the POSIX 12886 Threads Extension. 12887 Issue 6 12888 The following new requirements on POSIX implementations derive from alignment with the 12889 Single UNIX Specification: 12890 * The requirement to include has been removed. Although was 12891 required for conforming implementations of previous POSIX specifications, it was not 12892 required for UNIX applications. 12893 The following changes were made to align with the IEEE P1003.1a draft standard: 12894 * The effect of fork( ) on a pending alarm call in the child process is clarified. 12895 The description of CPU-time clock semantics is added for alignment with 12896 IEEE Std. 1003.1d-1999. | 12897 The description of tracing semantics is added for alignment with IEEE Std. 1003.1q-2000. | System Interfaces, Issue 6 891 fpathconf( ) System Interfaces 12898 NAME 12899 fpathconf, pathconf - get configurable path name variables 12900 SYNOPSIS 12901 #include 12902 long fpathconf(int fildes, int name); | 12903 long pathconf(const char *path, int name); | 12904 DESCRIPTION | 12905 The fpathconf( ) and pathconf( ) functions provide a method for the application to determine the 12906 current value of a configurable limit or option (variable) that is associated with a file or directory. 12907 For pathconf( ), the path argument points to the path name of a file or directory. 12908 For fpathconf( ), the fildes argument is an open file descriptor. 12909 The name argument represents the variable to be queried relative to that file or directory. 12910 Implementations shall support all of the variables listed in the following table and may support 12911 others. The variables in the following table come from or and the 12912 symbolic constants, defined in , are the corresponding values used for name. Support 12913 for some path name configuration variables is dependent on implementation options (see 12914 shading and margin codes in the table below). Where an implementation option is not 12915 supported, the variable need not be supported. 12916 _____________________________________________________________________ 12917 _ Variable Value of name Notes ____________________________________________________________________ 12918 {FILESIZEBITS} _PC_FILESIZEBITS 3, 4 12919 {LINK_MAX} _PC_LINK_MAX 1 12920 {MAX_CANON} _PC_MAX_CANON 2 12921 {MAX_INPUT} _PC_MAX_INPUT 2 12922 {NAME_MAX} _PC_NAME_MAX 3,4 12923 {PATH_MAX} _PC_PATH_MAX 4, 5 12924 {PIPE_BUF} _PC_PIPE_BUF 6 12925 ADV {POSIX_ALLOC_SIZE_MIN} _PC_ALLOC_SIZE_MIN 12926 ADV {POSIX_REC_INCR_XFER_SIZE} _PC_REC_INCR_XFER_SIZE 12927 ADV {POSIX_REC_MAX_XFER_SIZE} _PC_REC_MAX_XFER_SIZE 12928 ADV {POSIX_REC_MIN_XFER_SIZE} _PC_REC_MIN_XFER_SIZE 12929 ADV {POSIX_REC_XFER_ALIGN} _PC_REC_XFER_ALIGN 12930 {SYMLINK_MAX} _PC_SYMLINK_MAX 4,9 12931 _POSIX_CHOWN_RESTRICTED _PC_CHOWN_RESTRICTED 7 12932 _POSIX_NO_TRUNC _PC_NO_TRUNC 3, 4 12933 _POSIX_VDISABLE _PC_VDISABLE 2 12934 _POSIX_ASYNC_IO _PC_ASYNC_IO 8 12935 _POSIX_PRIO_IO _PC_PRIO_IO 8 12936 _ _POSIX_SYNC_IO _PC_SYNC_IO 8 ____________________________________________________________________ 12937 Notes: 12938 1. If path or fildes refers to a directory, the value returned applies to the directory 12939 itself. 12940 2. If path or fildes does not refer to a terminal file, it is unspecified whether an 12941 implementation supports an association of the variable name with the specified 12942 file. 892 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fpathconf( ) 12943 3. If path or fildes refers to a directory, the value returned applies to file names 12944 within the directory. 12945 4. If path or fildes does not refer to a directory, it is unspecified whether an 12946 implementation supports an association of the variable name with the specified 12947 file. 12948 5. If path or fildes refers to a directory, the value returned is the maximum length 12949 of a relative path name when the specified directory is the working directory. 12950 6. If path refers to a FIFO, or fildes refers to a pipe or FIFO, the value returned 12951 applies to the referenced object. If path or fildes refers to a directory, the value 12952 returned applies to any FIFO that exists or can be created within the directory. 12953 If path or fildes refers to any other type of file, it is unspecified whether an 12954 implementation supports an association of the variable name with the specified 12955 file. 12956 7. If path or fildes refers to a directory, the value returned applies to any files, other 12957 than directories, that exist or can be created within the directory. 12958 8. If path or fildes refers to a directory, it is unspecified whether an implementation 12959 supports an association of the variable name with the specified file. 12960 9. If path or fildes refers to a directory, the value returned is the maximum length 12961 of the string that a symbolic link in that directory can contain. 12962 RETURN VALUE 12963 If name is an invalid value, both pathconf( ) and fpathconf( ) shall return -1 and set errno to 12964 indicate the error. 12965 If the variable corresponding to name has no limit for the path or file descriptor, both pathconf( ) 12966 and fpathconf( ) shall return -1 without changing errno. If the implementation needs to use path 12967 to determine the value of name and the implementation does not support the association of name 12968 with the file specified by path, or if the process did not have appropriate privileges to query the 12969 file specified by path, or path does not exist, pathconf( ) shall return -1 and set errno to indicate the 12970 error. 12971 If the implementation needs to use fildes to determine the value of name and the implementation 12972 does not support the association of name with the file specified by fildes, or if fildes is an invalid 12973 file descriptor, fpathconf( ) shall return -1 and set errno to indicate the error. 12974 Otherwise, pathconf( ) or fpathconf( ) shall return the current variable value for the file or 12975 directory without changing errno. The value returned shall not be more restrictive than the 12976 corresponding value available to the application when it was compiled with the 12977 implementation's or . 12978 ERRORS 12979 The pathconf( ) function shall fail if: 12980 [EINVAL] The value of name is not valid. | 12981 [ELOOP] A loop exists in symbolic links encountered during resolution of the path | 12982 argument. | 12983 The pathconf( ) function may fail if: 12984 [EACCES] Search permission is denied for a component of the path prefix. | 12985 [EINVAL] The implementation does not support an association of the variable name with | 12986 the specified file. System Interfaces, Issue 6 893 fpathconf( ) System Interfaces 12987 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 12988 resolution of the path argument. 12989 [ENAMETOOLONG] | 12990 The length of the path argument exceeds {PATH_MAX} or a path name 12991 component is longer than {NAME_MAX}. | 12992 [ENAMETOOLONG] | 12993 As a result of encounering a symbolic link in resolution of the path argument, 12994 the length of the substituted path name string exceeded {PATH_MAX}. | 12995 [ENOENT] A component of path does not name an existing file or path is an empty string. | 12996 [ENOTDIR] A component of the path prefix is not a directory. | 12997 The fpathconf( ) function shall fail if: 12998 [EINVAL] The value of name is not valid. | 12999 The fpathconf( ) function may fail if: 13000 [EBADF] The fildes argument is not a valid file descriptor. | 13001 [EINVAL] The implementation does not support an association of the variable name with | 13002 the specified file. 13003 EXAMPLES 13004 None. 13005 APPLICATION USAGE 13006 None. 13007 RATIONALE 13008 The pathconf( ) function was proposed immediately after the sysconf( ) function when it was 13009 realized that some configurable values may differ across file system, directory, or device 13010 boundaries. 13011 For example, {NAME_MAX} frequently changes between System V and BSD-based file systems; 13012 System V uses a maximum of 14, BSD 255. On an implementation that provides both types of file 13013 systems, an application would be forced to limit all path name components to 14 bytes, as this 13014 would be the value specified in on such a system. 13015 Therefore, various useful values can be queried on any path name or file descriptor, assuming 13016 that the appropriate permissions are in place. 13017 The value returned for the variable {PATH_MAX} indicates the longest relative path name that 13018 could be given if the specified directory is the process' current working directory. A process may 13019 not always be able to generate a name that long and use it if a subdirectory in the path name 13020 crosses into a more restrictive file system. 13021 The value returned for the variable _POSIX_CHOWN_RESTRICTED also applies to directories 13022 that do not have file systems mounted on them. The value may change when crossing a mount 13023 point, so applications that need to know should check for each directory. (An even easier check 13024 is to try the chown( ) function and look for an error in case it happens.) 13025 Unlike the values returned by sysconf( ), the path name-oriented variables are potentially more 13026 volatile and are not guaranteed to remain constant throughout the process' lifetime. For 13027 example, in between two calls to pathconf( ), the file system in question may have been 13028 unmounted and remounted with different characteristics. 894 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fpathconf( ) 13029 Also note that most of the errors are optional. If one of the variables always has the same value 13030 on an implementation, the implementation need not look at path or fildes to return that value and 13031 is, therefore, not required to detect any of the errors except the meaning of [EINVAL] that | 13032 indicates that the value of name is not valid for that variable. 13033 If the value of any of the limits are indeterminate (logically infinite), they are defined in 13034 and the pathconf( ) and fpathconf( ) functions return -1 without changing errno. This 13035 can be distinguished from the case of giving an unrecognized name argument because errno is set 13036 to [EINVAL] in this case. 13037 Since -1 is a valid return value for the pathconf( ) and fpathconf( ) functions, applications should 13038 set errno to zero before calling them and check errno only if the return value is -1. 13039 For the case of {SYMLINK_MAX}, since both pathconf( ) and open( ) follow symbolic links, there 13040 is no way that path or fildes could refer to a symbolic link. 13041 FUTURE DIRECTIONS 13042 None. 13043 SEE ALSO 13044 confstr( ), sysconf( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , , | 13045 the Shell and Utilities volume of IEEE Std. 1003.1-200x | 13046 CHANGE HISTORY 13047 First released in Issue 3. 13048 Entry included for alignment with the POSIX.1-1988 standard. 13049 Issue 4 13050 The fpathconf( ) function now has the full long return type in the SYNOPSIS section. | 13051 The following changes gave been made for alignment with the ISO POSIX-1 standard: 13052 * The type of argument path is changed from char* to const char*. Also, the return value of 13053 both functions is changed from long to long. | 13054 * In the DESCRIPTION, the words ``The behavior is undefined if'' have been replaced by ``it is 13055 unspecified whether an implementation supports an association of the variable name with 13056 the specified file'' in notes 2, 4, and 6. 13057 * In the RETURN VALUE section, errors associated with the use of path and fildes, when an 13058 implementation does not support the requested association, are now specified separately. 13059 * The requirement that errno be set to indicate the error is added. 13060 The following change is incorporated for alignment with the FIPS requirements: 13061 * In the ERRORS section, the condition whereby [ENAMETOOLONG] is returned if a path 13062 name component is larger that {NAME_MAX} is now defined as mandatory and marked as 13063 an extension. 13064 Issue 4, Version 2 13065 The ERRORS section is updated for X/OPEN UNIX conformance as follows: 13066 * It states that [ELOOP] is returned if too many symbolic links are encountered during path 13067 name resolution. 13068 * A second [ENAMETOOLONG] condition is defined that may report excessive length of an 13069 intermediate result of path name resolution of a symbolic link. System Interfaces, Issue 6 895 fpathconf( ) System Interfaces 13070 Issue 5 13071 The DESCRIPTION is updated for alignment with the POSIX Realtime Extension. 13072 Large File Summit extensions are added. 13073 Issue 6 13074 The following changes are made for alignment with the ISO POSIX-1: 1996 standard: 13075 * The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. 13076 This is since behavior may vary from one file system to another. 13077 The following new requirements on POSIX implementations derive from alignment with the 13078 Single UNIX Specification: 13079 * The DESCRIPTION is updated to include {FILESIZEBITS}. 13080 * The [ELOOP] mandatory error condition is added. 13081 * A second [ENAMETOOLONG] is added as an optional error condition. 13082 The following changes were made to align with the IEEE P1003.1a draft standard: 13083 * The _PC_SYMLINK_MAX entry is added to the table in the DESCRIPTION. 13084 The pathconf( ) variables {POSIX_ALLOC_SIZE_MIN}, {POSIX_REC_INCR_XFER_SIZE}, 13085 {POSIX_REC_MAX_XFER_SIZE}, {POSIX_REC_MIN_XFER_SIZE}, 13086 {POSIX_REC_XFER_ALIGN} and their associated names are added for alignment with | 13087 IEEE Std. 1003.1d-1999. 896 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fpclassify( ) 13088 NAME | 13089 fpclassify - classify real floating type | 13090 SYNOPSIS | 13091 #include | 13092 int fpclassify(real-floating x); | 13093 DESCRIPTION | 13094 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 13095 conflict between the requirements described here and the ISO C standard is unintentional. This | 13096 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 13097 The fpclassify( ) macro shall classify its argument value as NaN, infinite, normal, subnormal, | 13098 zero, or into another implementation-defined category. First, an argument represented in a | 13099 format wider than its semantic type is converted to its semantic type. Then classification is based | 13100 on the type of the argument. | 13101 RETURN VALUE | 13102 The fpclassify( ) macro shall return the value of the number classification macro appropriate to | 13103 the value of its argument. | 13104 ERRORS | 13105 No errors are defined. | 13106 EXAMPLES | 13107 None. | 13108 APPLICATION USAGE | 13109 None. | 13110 RATIONALE | 13111 None. | 13112 FUTURE DIRECTIONS | 13113 None. | 13114 SEE ALSO | 13115 isfinite( ), isinf( ), isnan( ), isnormal( ), signbit( ), the Base Definitions volume of | 13116 IEEE Std. 1003.1-200x, | 13117 CHANGE HISTORY || 13118 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 897 fprintf( ) System Interfaces 13119 NAME 13120 fprintf, printf, snprintf, sprintf - print formatted output 13121 SYNOPSIS 13122 #include 13123 int fprintf(FILE *restrict stream, const char *restrict format, ...); | 13124 int printf(const char *restrict format, ...); | 13125 int snprintf(char *restrict s, size_t n, const char *restrict format, ...);| 13126 int sprintf(char *restrict s, const char *restrict format, ...); | 13127 DESCRIPTION | 13128 CX The functionality described on this reference page is aligned with the ISO C standard. Any 13129 conflict between the requirements described here and the ISO C standard is unintentional. This 13130 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 13131 The fprintf( ) function places output on the named output stream. The printf( ) function places 13132 output on the standard output stream stdout. The sprintf( ) function places output followed by 13133 the null byte, '\0', in consecutive bytes starting at *s; it is the user's responsibility to ensure that 13134 enough space is available. 13135 XSI The snprintf( ) function is identical to sprintf( ) with the addition of the n argument, which states 13136 the size of the buffer referred to by s. If n is greater than zero, but not large enough to hold all 13137 output bytes specified by the format, output bytes beyond the n-1st are discarded rather than 13138 being written into the array. 13139 If copying takes place between objects that overlap as a result of a call to sprintf( ) or snprintf( ), 13140 the results are undefined. 13141 Each of these functions converts, formats, and prints its arguments under control of the format. 13142 The format is a character string, beginning and ending in its initial shift state, if any. The format is 13143 composed of zero or more directives: ordinary characters, which are simply copied to the output 13144 stream, and conversion specifications, each of which results in the fetching of zero or more 13145 arguments. The results are undefined if there are insufficient arguments for the format. If the 13146 format is exhausted while arguments remain, the excess arguments are evaluated but are 13147 otherwise ignored. 13148 XSI Conversions can be applied to the nth argument after the format in the argument list, rather than 13149 to the next unused argument. In this case, the conversion character '%' (see below) is replaced 13150 by the sequence "%n$", where n is a decimal integer in the range [1,{NL_ARGMAX}], giving the 13151 position of the argument in the argument list. This feature provides for the definition of format 13152 strings that select arguments in an order appropriate to specific languages (see the EXAMPLES 13153 section). 13154 In format strings containing the "%n$" form of conversion specifications, numbered arguments 13155 in the argument list can be referenced from the format string as many times as required. 13156 In format strings containing the '%' form of conversion specifications, each argument in the 13157 argument list is used exactly once. 13158 All forms of the fprintf( ) functions allow for the insertion of a language-dependent radix 13159 character in the output string. The radix character is defined in the program's locale (category 13160 LC_NUMERIC). In the POSIX locale, or in a locale where the radix character is not defined, the 13161 radix character defaults to a period ('.'). 13162 XSI Each conversion specification is introduced by the '%' character or by the character sequence 13163 "%n$",after which the following appear in sequence: 898 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fprintf( ) 13164 * Zero or more flags (in any order), which modify the meaning of the conversion specification. 13165 * An optional minimum field width. If the converted value has fewer bytes than the field 13166 width, it shall be padded with spaces by default on the left; it shall be padded on the right, if 13167 the left-adjustment flag ('-'), described below, is given to the field width. The field width 13168 takes the form of an asterisk ('*'), described below, or a decimal integer. 13169 * An optional precision that gives the minimum number of digits to appear for the d, i, o, u, x, 13170 and X conversions; the number of digits to appear after the radix character for the e, E, and f 13171 conversions; the maximum number of significant digits for the g and G conversions; or the 13172 XSI maximum number of bytes to be printed from a string in s and S conversions. The precision 13173 takes the form of a period ('.') followed either by an asterisk ('*'), described below, or an 13174 optional decimal digit string, where a null digit string is treated as 0. If a precision appears 13175 with any other conversion character, the behavior is undefined. 13176 * An optional length modifier that specifies the size of the argument. | 13177 * A conversion character that indicates the type of conversion to be applied. 13178 A field width, or precision, or both, may be indicated by an asterisk ('*'). In this case an 13179 argument of type int supplies the field width or precision. Applications shall ensure that 13180 arguments specifying field width, or precision, or both appear in that order before the argument, 13181 if any, to be converted. A negative field width is taken as a '-' flag followed by a positive field 13182 XSI width. A negative precision is taken as if the precision were omitted. In format strings 13183 containing the "%n$" form of a conversion specification, a field width or precision may be 13184 indicated by the sequence "*m$", where m is a decimal integer in the range [1,{NL_ARGMAX}] 13185 giving the position in the argument list (after the format argument) of an integer argument 13186 containing the field width or precision, for example: 13187 printf("%1$d:%2$.*3$d:%4$.*3$d\n", hour, min, precision, sec); 13188 The format can contain either numbered argument specifications (that is, "%n$" and "*m$"), or 13189 unnumbered argument specifications (that is, '%' and '*'), but normally not both. The only 13190 exception to this is that "%%" can be mixed with the "%n$" form. The results of mixing 13191 numbered and unnumbered argument specifications in a format string are undefined. When 13192 numbered argument specifications are used, specifying the Nth argument requires that all the 13193 leading arguments, from the first to the (N-1)th, are specified in the format string. 13194 The flag characters and their meanings are: 13195 XSI ' The integer portion of the result of a decimal conversion (%i, %d, %u, %f, %g, or %G) 13196 shall be formatted with thousands' grouping characters. For other conversions the 13197 behavior is undefined. The non-monetary grouping character is used. 13198 - The result of the conversion shall be left-justified within the field. The conversion is 13199 right-justified if this flag is not specified. 13200 + The result of a signed conversion shall always begin with a sign ('+' or '-'). The 13201 conversion shall begin with a sign only when a negative value is converted if this flag is 13202 not specified. 13203 If the first character of a signed conversion is not a sign or if a signed conversion results 13204 in no characters, a space shall be prefixed to the result. This means that if the space and 13205 '+' flags both appear, the space flag shall be ignored. 13206 # This flag specifies that the value is to be converted to an alternative form. For o 13207 conversion, it increases the precision (if necessary) to force the first digit of the result to 13208 be 0. For x or X conversions, a non-zero result shall have 0x (or 0X) prefixed to it. For e, 13209 E, f, g, or G conversions, the result shall always contain a radix character, even if no System Interfaces, Issue 6 899 fprintf( ) System Interfaces 13210 digits follow the radix character. Without this flag, a radix character appears in the 13211 result of these conversions only if a digit follows it. For g and G conversions, trailing 13212 zeros shall not be removed from the result as they normally are. For other conversions, 13213 the behavior is undefined. 13214 0 For d, i, o, u, x, X, e, E, f, g, and G conversions, leading zeros (following any indication of 13215 sign or base) are used to pad to the field width; no space padding is performed. If the | 13216 '0' and '-' flags both appear, the '0' flag is ignored. For d, i, o, u, x, and X | 13217 XSI conversions, if a precision is specified, the '0' flag is ignored. If the '0' and '\'' | 13218 flags both appear, the grouping characters are inserted before zero padding. For other 13219 conversions, the behavior is undefined. | 13220 The length modifiers and their meanings are: | 13221 hh Specifies that a following d, i, o, u, x, or X conversion specifier applies to a signed char | 13222 or unsigned char argument (the argument will have been promoted according to the | 13223 integer promotions, but its value shall be converted to signed char or unsigned char | 13224 before printing); or that a following n conversion specifier applies to a pointer to a | 13225 signed char argument. | 13226 h Specifies that a following d, i, o, u, x, or X conversion specifier applies to a short or | 13227 unsigned short argument (the argument will have been promoted according to the | 13228 integer promotions, but its value shall be converted to short or unsigned short before | 13229 printing); or that a following n conversion specifier applies to a pointer to a short | 13230 argument. | 13231 l (ell) Specifies that a following d, i, o, u, x, or X conversion specifier applies to a long or | 13232 unsigned long argument; that a following n conversion specifier applies to a pointer to | 13233 a long argument; that a following c conversion specifier applies to a wint_t argument; | 13234 that a following s conversion specifier applies to a pointer to a wchar_t argument; or | 13235 has no effect on a following a, A, e, E, f, F, g, or G conversion specifier. | 13236 ll (ell-ell)Specifies that a following d, i, o, u, x, or X conversion specifier applies to a long long or | 13237 unsigned long long argument; or that a following n conversion specifier applies to a | 13238 pointer to a long long argument. | 13239 j Specifies that a following d, i, o, u, x, or X conversion specifier applies to an intmax_t or | 13240 uintmax_t argument; or that a following n conversion specifier applies to a pointer to | 13241 an intmax_t argument. | 13242 z Specifies that a following d, i, o, u, x, or X conversion specifier applies to a size_t or the | 13243 corresponding signed integer type argument; or that a following n conversion specifier | 13244 applies to a pointer to a signed integer type corresponding to size_t argument. | 13245 t Specifies that a following d, i, o, u, x, or X conversion specifier applies to a ptrdiff_t or | 13246 the corresponding unsigned type argument; or that a following n conversion specifier | 13247 applies to a pointer to a ptrdiff_t argument. | 13248 L Specifies that a following a, A, e, E, f, F, g, orG conversion specifier applies to a long | 13249 double argument. | 13250 If a length modifier appears with any conversion specifier other than as specified above, the | 13251 behavior is undefined. | 13252 The conversion characters and their meanings are: | 13253 d, i The int argument is converted to a signed decimal in the style [-]dddd. The precision 13254 specifies the minimum number of digits to appear; if the value being converted can be 13255 represented in fewer digits, it shall be expanded with leading zeros. The default 900 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fprintf( ) 13256 precision is 1. The result of converting 0 with an explicit precision of 0 is no characters. 13257 o The unsigned argument is converted to unsigned octal format in the style dddd. The | 13258 precision specifies the minimum number of digits to appear; if the value being 13259 converted can be represented in fewer digits, it shall be expanded with leading zeros. 13260 The default precision is 1. The result of converting 0 with an explicit precision of 0 is no 13261 characters. 13262 u The unsigned argument is converted to unsigned decimal format in the style dddd. The | 13263 precision specifies the minimum number of digits to appear; if the value being 13264 converted can be represented in fewer digits, it shall be expanded with leading zeros. 13265 The default precision is 1. The result of converting 0 with an explicit precision of 0 is no 13266 characters. 13267 x The unsigned argument is converted to unsigned hexadecimal format in the style dddd; | 13268 the letters "abcdef" are used. The precision specifies the minimum number of digits 13269 to appear; if the value being converted can be represented in fewer digits, it shall be 13270 expanded with leading zeros. The default precision is 1. The result of converting 0 with 13271 an explicit precision of 0 is no characters. 13272 X Behaves the same as the x conversion character except that letters "ABCDEF" are used 13273 instead of "abcdef". | 13274 f, F The double argument is converted to decimal notation in the style [-]ddd.ddd, where | 13275 the number of digits after the radix character is equal to the precision specification. If 13276 the precision is missing, it is taken as 6; if the precision is explicitly 0 and no '#' flag is 13277 present, no radix character appears. If a radix character appears, at least one digit 13278 appears before it. The value is rounded to the appropriate number of digits. 13279 A double argument representing an infinity is converted in one of the styles [-]inf or | 13280 [-]infinity; which style is implementation-defined. A double argument representing a | 13281 NaN is converted in one of the styles [-]nan or [-]nan(n-char-sequence); which style, and | 13282 the meaning of any n-char-sequence, is implementation-defined. The F conversion | 13283 specifier produces INF, INFINITY, or NAN instead of inf, infinity, or nan, respectively. | 13284 e, E The double argument is converted in the style [-]d.ddde±dd, where there is one digit | 13285 before the radix character (which is non-zero if the argument is non-zero) and the 13286 number of digits after it is equal to the precision; if the precision is missing, it is taken 13287 as 6; if the precision is 0 and no '#' flag is present, no radix character appears. The 13288 value is rounded to the appropriate number of digits. The E conversion character will 13289 produce a number with E instead of e introducing the exponent. The exponent always 13290 contains at least two digits. If the value is 0, the exponent is 0. 13291 A double argument representing an infinity or NaN is converted in the style of an f or F | 13292 conversion specifier. | 13293 g, G The double argument is converted in the style f or e (or in the style E in the case of a G | 13294 conversion character), with the precision specifying the number of significant digits. If 13295 an explicit precision is 0, it is taken as 1. The style used depends on the value 13296 converted; style e (or E) shall be used only if the exponent resulting from such a 13297 conversion is less than -4 or greater than or equal to the precision. Trailing zeros are 13298 removed from the fractional portion of the result; a radix character appears only if it is 13299 followed by a digit. 13300 A double argument representing an infinity or NaN is converted in the style of an f or F | 13301 conversion specifier. | System Interfaces, Issue 6 901 fprintf( ) System Interfaces 13302 a, A A double argument representing a floating-point number is converted in the style | 13303 [-]0xh.hhhh p1d, where there is one hexadecimal digit (which is non-zero if the | 13304 argument is a normalized floating-point number and is otherwise unspecified) before | 13305 the decimal-point character 235) and the number of hexadecimal digits after it is equal | 13306 to the precision; if the precision is missing and FLT_RADIX is a power of 2, then the | 13307 precision is sufficient for an exact representation of the value; if the precision is missing | 13308 and FLT_RADIX is not a power of 2, then the precision is sufficient to distinguish 236) | 13309 values of type double, except that trailing zeros may be omitted; if the precision is zero | 13310 and the '#' flag is not specified, no decimal-point character appears. The letters | 13311 "abcdef" are used for a conversion and the letters "ABCDEF" for A conversion. The A | 13312 conversion specifier produces a number with 'X' and 'P' instead of 'x' and 'p'. | 13313 The exponent always contains at least one digit, and only as many more digits as | 13314 necessary to represent the decimal exponent of 2. If the value is zero, the exponent is | 13315 zero. | 13316 A double argument representing an infinity or NaN is converted in the style of an f or F | 13317 conversion specifier. | 13318 c The int argument is converted to an unsigned char, and the resulting byte is written. 13319 If an l (ell) qualifier is present, the wint_t argument is converted as if by an ls 13320 conversion specification with no precision and an argument that points to a two- 13321 element array of type wchar_t, the first element of which contains the wint_t argument 13322 to the ls conversion specification and the second element contains a null wide 13323 character. 13324 s The argument shall be a pointer to an array of char. Bytes from the array are written up 13325 to (but not including) any terminating null byte. If the precision is specified, no more 13326 than that many bytes shall be written. If the precision is not specified or is greater than 13327 the size of the array, the application shall ensure that the array contains a null byte. 13328 If an l (ell) qualifier is present, the argument shall be a pointer to an array of type 13329 wchar_t. Wide characters from the array are converted to characters (each as if by a 13330 call to the wcrtomb( ) function, with the conversion state described by an mbstate_t 13331 object initialized to zero before the first wide character is converted) up to and 13332 including a terminating null wide character. The resulting characters shall be written 13333 up to (but not including) the terminating null character (byte). If no precision is 13334 specified, the application shall ensure that the array contains a null wide character. If a 13335 precision is specified, no more than that many characters (bytes) shall be written 13336 (including shift sequences, if any), and the array shall contain a null wide character if, 13337 to equal the character sequence length given by the precision, the function would need 13338 to access a wide character one past the end of the array. In no case is a partial character 13339 written. 13340 p The argument shall be a pointer to void. The value of the pointer is converted to a 13341 sequence of printable characters, in an implementation-defined manner. | 13342 n The argument shall be a pointer to an integer into which is written the number of bytes 13343 written to the output so far by this call to one of the fprintf( ) functions. No argument is 13344 converted. 13345 XSI C Same as lc. 13346 XSI S Same as ls. 13347 % Print a '%'; no argument is converted. The entire conversion specification shall be 13348 "%%". 902 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fprintf( ) 13349 If a conversion specification does not match one of the above forms, the behavior is undefined. If | 13350 any argument is not the correct type for the corresponding conversion specification, the | 13351 behavior is undefined. | 13352 In no case does a nonexistent or small field width cause truncation of a field; if the result of a 13353 conversion is wider than the field width, the field is simply expanded to contain the conversion 13354 result. Characters generated by fprintf( ) and printf( ) are printed as if fputc( ) had been called. 13355 For a and A conversions, if FLT_RADIX is a power of 2, the value is correctly rounded to a | 13356 hexadecimal floating number with the given precision. | 13357 If FLT_RADIX is not a power of 2, the result should be one of the two adjacent numbers in | 13358 hexadecimal floating style with the given precision, with the extra stipulation that the error | 13359 should have a correct sign for the current rounding direction. | 13360 For e, E, f, F, g, and G conversions, if the number of significant decimal digits is at most | 13361 DECIMAL_DIG, then the result should be correctly rounded. If the number of significant | 13362 decimal digits is more than DECIMAL_DIG but the source value is exactly representable with | 13363 DECIMAL_DIG digits, then the result should be an exact representation with trailing zeros. | 13364 Otherwise, the source value is bounded by two adjacent decimal strings "L < U", both having | 13365 DECIMAL_DIG significant digits; the value of the resultant decimal string "D" should satisfy "L | 13366 <= D <= U", with the extra stipulation that the error should have a correct sign for the current | 13367 rounding direction. | 13368 CX The st_ctime and st_mtime fields of the file shall be marked for update between the call to a | 13369 successful execution of fprintf( ) or printf( ) and the next successful completion of a call to fflush( ) 13370 or fclose( ) on the same stream or a call to exit( ) or abort( ). 13371 RETURN VALUE 13372 Upon successful completion, the fprintf( ) and printf( ) functions shall return the number of bytes 13373 transmitted. 13374 Upon successful completion, the sprintf( ) function shall return the number of bytes written to s, 13375 excluding the terminating null byte. 13376 Upon successful completion, the snprintf( ) function shall return the number of bytes that would | 13377 be written to s had n been sufficiently large excluding the terminating null byte. | 13378 If an output error was encountered, these functions shall return a negative value. 13379 If the value of n is zero on a call to snprintf( ), nothing shall be written, the number of bytes that | 13380 would have been written had n been sufficiently large excluding the terminating null shall be | 13381 returned, and s may be a null pointer. | 13382 ERRORS 13383 For the conditions under which fprintf( ) and printf( ) fail and may fail, refer to fputc( ) or 13384 fputwc( ). 13385 In addition, all forms of fprintf( ) may fail if: 13386 XSI [EILSEQ] A wide-character code that does not correspond to a valid character has been | 13387 detected. 13388 XSI [EINVAL] There are insufficient arguments. | 13389 The printf( ) and fprintf( ) functions may fail if: 13390 XSI [ENOMEM] Insufficient storage space is available. | 13391 The snprintf( ) function shall fail if: System Interfaces, Issue 6 903 fprintf( ) System Interfaces 13392 XSI [EOVERFLOW] The value of n is greater than {INT_MAX} or the number of bytes needed to 13393 hold the output excluding the terminating null is greater than {INT_MAX}. 13394 EXAMPLES 13395 Printing Language-Independent Date and Time 13396 The following statement can be used to print date and time using a language-independent 13397 format: 13398 printf(format, weekday, month, day, hour, min); 13399 For American usage, format could be a pointer to the following string: 13400 "%s, %s %d, %d:%.2d\n" 13401 This example would produce the following message: 13402 Sunday, July 3, 10:02 13403 For German usage, format could be a pointer to the following string: 13404 "%1$s, %3$d. %2$s, %4$d:%5$.2d\n" 13405 This definition of format would produce the following message: 13406 Sonntag, 3. Juli, 10:02 13407 Printing File Information 13408 The following example prints information about the type, permissions, and number of links of a 13409 specific file in a directory. 13410 The first two calls to printf( ) use data decoded from a previous stat( ) call. The user-defined 13411 strperm( ) function shall return a string similar to the one at the beginning of the output for the 13412 following command: 13413 ls -l 13414 The next call to printf( ) outputs the owner's name if it is found using getpwuid( ); the getpwuid( ) 13415 function shall return a passwd structure from which the name of the user is extracted. If the user 13416 name is not found, the program instead prints out the numeric value of the user ID. 13417 The next call prints out the group name if it is found using getgrgid( ); getgrgid( ) is very similar to 13418 getpwuid( ) except that it shall return group information based on the group number. Once 13419 again, if the group is not found, the program prints the numeric value of the group for the entry. 13420 The final call to printf( ) prints the size of the file. 13421 #include 13422 #include 13423 #include 13424 #include 13425 char *strperm (mode_t); 13426 ... 13427 struct stat statbuf; 13428 struct passwd *pwd; 13429 struct group *grp; 13430 ... 13431 printf("%10.10s", strperm (statbuf.st_mode)); 904 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fprintf( ) 13432 printf("%4d", statbuf.st_nlink); 13433 if ((pwd = getpwuid(statbuf.st_uid)) != NULL) 13434 printf(" %-8.8s", pwd->pw_name); 13435 else 13436 printf(" %-8ld", (long) statbuf.st_uid); 13437 if ((grp = getgrgid(statbuf.st_gid)) != NULL) 13438 printf(" %-8.8s", grp->gr_name); 13439 else 13440 printf(" %-8ld", (long) statbuf.st_gid); 13441 printf("%9jd", (intmax_t) statbuf.st_size); 13442 ... 13443 Printing a Localized Date String 13444 The following example gets a localized date string. The nl_langinfo ( ) function shall return the 13445 localized date string, which specifies the order and layout of the date. The strftime( ) function 13446 takes this information and, using the tm structure for values, places the date and time 13447 information into datestring. The printf( ) function then outputs datestring and the name of the 13448 entry. 13449 #include 13450 #include 13451 #include 13452 ... 13453 struct dirent *dp; 13454 struct tm *tm; 13455 char datestring[256]; 13456 ... 13457 strftime(datestring, sizeof(datestring), nl_langinfo (D_T_FMT), tm); 13458 printf(" %s %s\n", datestring, dp->d_name); 13459 ... 13460 Printing Error Information 13461 The following example uses fprintf( ) to write error information to stadard error. 13462 In the first group of calls, the program tries to open the password lock file named LOCKFILE. If 13463 the file already exists, this is an error, as indicated by the O_EXCL flag on the open( ) function. If 13464 the call fails, the program assumes that someone else is updating the password file, and the 13465 program exits. 13466 The next group of calls saves a new password file as the current password file by creating a link 13467 between LOCKFILE and the new password file PASSWDFILE. 13468 #include 13469 #include 13470 #include 13471 #include 13472 #include 13473 #include 13474 #include 13475 #include System Interfaces, Issue 6 905 fprintf( ) System Interfaces 13476 #define LOCKFILE "/etc/ptmp" 13477 #define PASSWDFILE "/etc/passwd" 13478 ... 13479 int pfd; 13480 ... 13481 if ((pfd = open(LOCKFILE, O_WRONLY | O_CREAT | O_EXCL, 13482 S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) == -1) 13483 { 13484 fprintf(stderr, "Cannot open /etc/ptmp. Try again later.\n"); 13485 exit(1); 13486 } 13487 ... 13488 if (link(LOCKFILE,PASSWDFILE) == -1) { 13489 fprintf(stderr, "Link error: %s\n", strerror(errno)); 13490 exit(1); 13491 } 13492 ... 13493 Printing Usage Information 13494 The following example checks to make sure the program has the necessary arguments, and uses 13495 fprintf( ) to print usage information if the expected number of arguments is not present. 13496 #include 13497 #include 13498 ... 13499 char *Options = "hdbtl"; 13500 ... 13501 if (argc < 2) { 13502 fprintf(stderr, "Usage: %s -%s 13510 ... 13511 long i; 13512 char *keystr; 13513 int elementlen, len; 13514 ... 13515 while (len < elementlen) { 13516 ... 13517 printf("%s Element%0*ld\n", keystr, elementlen, i); 13518 ... 13519 } 906 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fprintf( ) 13520 Creating a File Name 13521 The following example creates a file name using information from a previous getpwnam( ) 13522 function that returned the HOME directory of the user. 13523 #include 13524 #include 13525 #include 13526 ... 13527 char filename[PATH_MAX+1]; 13528 struct passwd *pw; 13529 ... 13530 sprintf(filename, "%s/%d.out", pw->pw_dir, getpid()); 13531 ... 13532 Reporting an Event 13533 The following example loops until an event has timed out. The pause( ) function waits forever 13534 unless it receives a signal. The fprintf( ) statement should never occur due to the possible return 13535 values of pause( ). 13536 #include 13537 #include 13538 #include 13539 #include 13540 ... 13541 while (!event_complete) { 13542 ... 13543 if (pause() != -1 || errno != EINTR) 13544 fprintf(stderr, "pause: unknown error: %s\n", strerror(errno)); 13545 } 13546 ... 13547 Printing Monetary Information 13548 The following example uses strfmon( ) to convert a number and store it as a formatted monetary 13549 string named convbuf. If the first number is printed, the program prints the format and the 13550 description; otherwise, it just prints the number. 13551 #include 13552 #include 13553 ... 13554 struct tblfmt { 13555 char *format; 13556 char *description; 13557 }; 13558 struct tblfmt table[] = { 13559 { "%n", "default formatting" }, 13560 { "%11n", "right align within an 11 character field" }, 13561 { "%#5n", "aligned columns for values up to 99,999" }, 13562 { "%=*#5n", "specify a fill character" }, 13563 { "%=0#5n", "fill characters do not use grouping" }, 13564 { "% #5n", "disable the grouping separator" }, 13565 { "% #5.0n", "round off to whole units" }, System Interfaces, Issue 6 907 fprintf( ) System Interfaces 13566 { "% #5.4n", "increase the precision" }, 13567 { "%(#5n", "use an alternative pos/neg style" }, 13568 { "%!(#5n", "disable the currency symbol" }, 13569 }; 13570 ... 13571 float input[3]; 13572 int i, j; 13573 char convbuf[100]; 13574 ... 13575 strfmon(convbuf, sizeof(convbuf), table[i].format, input[j]); 13576 if (j == 0) { 13577 printf("%s%s%s\n", table[i].format, 13578 convbuf, table[i].description); 13579 } 13580 else { 13581 printf("%s\n", convbuf); 13582 } 13583 ... 13584 APPLICATION USAGE 13585 If the application calling fprintf( ) has any objects of type wint_t or wchar_t, it must also include 13586 the header to have these objects defined. 13587 RATIONALE 13588 None. 13589 FUTURE DIRECTIONS 13590 None. 13591 SEE ALSO 13592 fputc( ), fscanf( ), setlocale( ), wcrtomb( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 13593 , , the Base Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale | 13594 CHANGE HISTORY 13595 First released in Issue 1. Derived from Issue 1 of the SVID. | 13596 Issue 4 13597 In the DESCRIPTION, references to langinfo data are marked as extensions. The reference to 13598 langinfo data is removed from the description of the radix character. 13599 The ''' (single-quote) flag is added to the list of flag characters and marked as an extension. 13600 This flag directs that numeric conversion is formatted with the decimal grouping character. 13601 The detailed description of these functions is provided here instead of under printf( ). 13602 The information in the APPLICATION USAGE section is moved to the DESCRIPTION. A new 13603 APPLICATION USAGE section is added. 13604 The [EILSEQ] error is added to the ERRORS section and all errors are marked as extensions. 13605 The following changes are incorporated for alignment with the ISO C standard: 13606 * The type of the format arguments is changed from char* to const char*. 13607 * The DESCRIPTION is reworded or presented differently in a number of places for alignment 13608 with the ISO C standard, and also for clarity. There are no functional changes, except as 13609 noted elsewhere in this CHANGE HISTORY section. 908 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fprintf( ) 13610 The following changes are incorporated for alignment with the MSE working draft: 13611 * The C and S conversion characters are added, indicating respectively a wide character of type 13612 wchar_t and pointer to a wide-character string of type wchar_t* in the argument list. 13613 Issue 4, Version 2 13614 The [ENOMEM] error is added to the ERRORS section as an optional error. 13615 Issue 5 13616 Aligned with ISO/IEC 9899: 1990/Amendment 1: 1995 (E). Specifically, the l (ell) qualifier can 13617 now be used with c and s conversion characters. 13618 The snprintf( ) function is new in Issue 5. 13619 Issue 6 13620 Extensions beyond the ISO C standard are now marked. 13621 The description of snprintf( ) has been aligned with The Open Group Base Resolution bwg98-006. 13622 This aligns snprintf( ) with historic BSD behavior. 13623 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. | 13624 The following changes are made for alignment with the ISO/IEC 9899: 1999 standard: | 13625 * The prototypes for fprintf( ), printf( ), snprintf( ), and sprintf( ) are updated, and the XSI | 13626 shading is removed from snprintf( ). || 13627 * The DESCRIPTION is updated. | System Interfaces, Issue 6 909 fputc( ) System Interfaces 13628 NAME 13629 fputc - put a byte on a stream 13630 SYNOPSIS 13631 #include 13632 int fputc(int c, FILE *stream); 13633 DESCRIPTION 13634 CX The functionality described on this reference page is aligned with the ISO C standard. Any 13635 conflict between the requirements described here and the ISO C standard is unintentional. This 13636 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 13637 The fputc( ) function shall write the byte specified by c (converted to an unsigned char) to the 13638 output stream pointed to by stream, at the position indicated by the associated file-position 13639 indicator for the stream (if defined), and advances the indicator appropriately. If the file cannot 13640 support positioning requests, or if the stream was opened with append mode, the byte shall be 13641 appended to the output stream. 13642 CX The st_ctime and st_mtime fields of the file shall be marked for update between the successful 13643 execution of fputc( ) and the next successful completion of a call to fflush( ) or fclose( ) on the same 13644 stream or a call to exit( ) or abort( ). 13645 RETURN VALUE 13646 Upon successful completion, fputc( ) shall return the value it has written. Otherwise, it shall 13647 CX return EOF, the error indicator for the stream shall be set, and errno shall be set to indicate the 13648 error. 13649 ERRORS 13650 The fputc( ) function shall fail if either the stream is unbuffered or the stream's buffer needs to be 13651 flushed, and: 13652 CX [EAGAIN] The O_NONBLOCK flag is set for the file descriptor underlying stream and the | 13653 process would be delayed in the write operation. 13654 CX [EBADF] The file descriptor underlying stream is not a valid file descriptor open for | 13655 writing. 13656 CX [EFBIG] An attempt was made to write to a file that exceeds the maximum file size. | 13657 XSI [EFBIG] An attempt was made to write to a file that exceeds the process' file size limit. | 13658 CX [EFBIG] The file is a regular file and an attempt was made to write at or beyond the | 13659 offset maximum. 13660 CX [EINTR] The write operation was terminated due to the receipt of a signal, and no data | 13661 was transferred. 13662 CX [EIO] A physical I/O error has occurred, or the process is a member of a | 13663 background process group attempting to write to its controlling terminal, 13664 TOSTOP is set, the process is neither ignoring nor blocking SIGTTOU, and the 13665 process group of the process is orphaned. This error may also be returned 13666 under implementation-defined conditions. | 13667 CX [ENOSPC] There was no free space remaining on the device containing the file. | 13668 CX [EPIPE] An attempt is made to write to a pipe or FIFO that is not open for reading by | 13669 any process. A SIGPIPE signal shall also be sent to the thread. 13670 The fputc( ) function may fail if: 910 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fputc( ) 13671 CX [ENOMEM] Insufficient storage space is available. | 13672 CX [ENXIO] A request was made of a nonexistent device, or the request was outside the | 13673 capabilities of the device. 13674 EXAMPLES 13675 None. 13676 APPLICATION USAGE 13677 None. 13678 RATIONALE 13679 None. 13680 FUTURE DIRECTIONS 13681 None. 13682 SEE ALSO 13683 ferror( ), fopen( ), getrlimit( ), putc( ), puts( ), setbuf( ), ulimit( ), the Base Definitions volume of | 13684 IEEE Std. 1003.1-200x, | 13685 CHANGE HISTORY 13686 First released in Issue 1. Derived from Issue 1 of the SVID. | 13687 Issue 4 13688 In the DESCRIPTION, the text is changed to make it clear that the function writes byte values, 13689 rather than (possibly multi-byte) character values. 13690 In the ERRORS section, text is added to indicate that error returns are only generated when 13691 either the stream is unbuffered, or if the stream buffer needs to be flushed. 13692 Also in the ERRORS section, in previous issues generation of the [EIO] error depended on 13693 whether or not an implementation supported Job Control. This functionality is now defined as 13694 mandatory. 13695 The [ENXIO] error is moved to the list of optional errors, and all the optional errors are marked 13696 as extensions. 13697 The description of [EINTR] is amended. 13698 The [EFBIG] error is marked to show extensions. 13699 Issue 4, Version 2 13700 In the ERRORS section, the description of [EIO] is updated to include the case where a physical 13701 I/O error occurs. 13702 Issue 5 13703 Large File Summit extensions are added. 13704 Issue 6 13705 Extensions beyond the ISO C standard are now marked. 13706 The following new requirements on POSIX implementations derive from alignment with the 13707 Single UNIX Specification: 13708 * The [EIO] and [EFBIG] mandatory error conditions are added. 13709 * The [ENOMEM] and [ENXIO] optional error conditions are added. System Interfaces, Issue 6 911 fputs( ) System Interfaces 13710 NAME 13711 fputs - put a string on a stream 13712 SYNOPSIS 13713 #include 13714 int fputs(const char *restrict s, FILE *restrict stream); | 13715 DESCRIPTION | 13716 CX The functionality described on this reference page is aligned with the ISO C standard. Any 13717 conflict between the requirements described here and the ISO C standard is unintentional. This 13718 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 13719 The fputs( ) function shall write the null-terminated string pointed to by s to the stream pointed 13720 to by stream. The terminating null byte shall not be written. 13721 CX The st_ctime and st_mtime fields of the file shall be marked for update between the successful 13722 execution of fputs( ) and the next successful completion of a call to fflush( ) or fclose( ) on the same 13723 stream or a call to exit( ) or abort( ). 13724 RETURN VALUE 13725 Upon successful completion, fputs( ) shall return a non-negative number. Otherwise, it shall 13726 CX return EOF, set an error indicator for the stream, and set errno to indicate the error. 13727 ERRORS 13728 Refer to fputc( ). 13729 EXAMPLES 13730 Printing to Standard Output 13731 The following example gets the current time, converts it to a string using localtime( ) and 13732 asctime( ), and prints it to standard output using fputs( ). It then prints the number of minutes to 13733 an event for which it is waiting. 13734 #include 13735 #include 13736 ... 13737 time_t now; 13738 int minutes_to_event; 13739 ... 13740 time(&now); 13741 printf("The time is "); 13742 fputs(asctime(localtime(&now)), stdout); 13743 printf("There are still %d minutes to the event.\n", 13744 minutes_to_event); 13745 ... 13746 APPLICATION USAGE 13747 The puts( ) function appends a character while fputs( ) does not. 13748 RATIONALE 13749 None. 13750 FUTURE DIRECTIONS 13751 None. 912 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fputs( ) 13752 SEE ALSO 13753 fopen( ), putc( ), puts( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 13754 CHANGE HISTORY 13755 First released in Issue 1. Derived from Issue 1 of the SVID. | 13756 Issue 4 13757 In the DESCRIPTION, the words ``null character'' are replaced by ``null byte'', to make it clear 13758 that this function deals solely in byte values. 13759 The following change is incorporated for alignment with the ISO C standard: 13760 * The type of argument s is changed from char* to const char*. 13761 Issue 6 13762 Extensions beyond the ISO C standard are now marked. | 13763 The fputs( ) prototype is updated for alignment with the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 913 fputwc( ) System Interfaces 13764 NAME 13765 fputwc - put a wide-character code on a stream 13766 SYNOPSIS 13767 #include 13768 #include 13769 wint_t fputwc(wchar_t wc, FILE *stream); 13770 DESCRIPTION 13771 CX The functionality described on this reference page is aligned with the ISO C standard. Any 13772 conflict between the requirements described here and the ISO C standard is unintentional. This 13773 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 13774 The fputwc( ) function shall write the character corresponding to the wide-character code wc to 13775 the output stream pointed to by stream, at the position indicated by the associated file-position 13776 indicator for the stream (if defined), and advances the indicator appropriately. If the file cannot 13777 support positioning requests, or if the stream was opened with append mode, the character is 13778 appended to the output stream. If an error occurs while writing the character, the shift state of | 13779 the output file is left in an undefined state. 13780 CX The st_ctime and st_mtime fields of the file shall be marked for update between the successful 13781 execution of fputwc( ) and the next successful completion of a call to fflush( ) or fclose( ) on the 13782 same stream or a call to exit( ) or abort( ). 13783 RETURN VALUE 13784 Upon successful completion, fputwc( ) shall return wc. Otherwise, it shall return WEOF, the error 13785 CX indicator for the stream shall be set set, and errno shall be set to indicate the error. 13786 ERRORS 13787 The fputwc( ) function shall fail if either the stream is unbuffered or data in the stream's buffer 13788 needs to be written, and: 13789 CX [EAGAIN] The O_NONBLOCK flag is set for the file descriptor underlying stream and the | 13790 process would be delayed in the write operation. 13791 CX [EBADF] The file descriptor underlying stream is not a valid file descriptor open for | 13792 writing. 13793 CX [EFBIG] An attempt was made to write to a file that exceeds the maximum file size or | 13794 the process' file size limit. 13795 CX [EFBIG] The file is a regular file and an attempt was made to write at or beyond the | 13796 offset maximum associated with the corresponding stream. 13797 CX [EINTR] The write operation was terminated due to the receipt of a signal, and no data | 13798 was transferred. 13799 CX [EIO] A physical I/O error has occurred, or the process is a member of a | 13800 background process group attempting to write to its controlling terminal, 13801 TOSTOP is set, the process is neither ignoring nor blocking SIGTTOU, and the 13802 process group of the process is orphaned. This error may also be returned 13803 under implementation-defined conditions. | 13804 CX [ENOSPC] There was no free space remaining on the device containing the file. | 13805 CX [EPIPE] An attempt is made to write to a pipe or FIFO that is not open for reading by | 13806 any process. A SIGPIPE signal shall also be sent to the thread. 914 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fputwc( ) 13807 The fputwc( ) function may fail if: 13808 CX [ENOMEM] Insufficient storage space is available. | 13809 CX [ENXIO] A request was made of a nonexistent device, or the request was outside the | 13810 capabilities of the device. 13811 CX [EILSEQ] The wide-character code wc does not correspond to a valid character. | 13812 EXAMPLES 13813 None. 13814 APPLICATION USAGE 13815 None. 13816 RATIONALE 13817 None. 13818 FUTURE DIRECTIONS 13819 None. 13820 SEE ALSO 13821 ferror( ), fopen( ), setbuf( ), ulimit( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 13822 , 13823 CHANGE HISTORY 13824 First released in Issue 4. Derived from the MSE working draft. | 13825 Issue 4, Version 2 13826 In the ERRORS section, the description of [EIO] is updated to include the case where a physical 13827 I/O error occurs. 13828 Issue 5 13829 Aligned with ISO/IEC 9899: 1990/Amendment 1: 1995 (E). Specifically, the type of argument wc 13830 is changed from wint_t to wchar_t. 13831 The Optional Header (OH) marking is removed from . 13832 Large File Summit extensions are added. 13833 Issue 6 13834 Extensions beyond the ISO C standard are now marked. 13835 The following new requirements on POSIX implementations derive from alignment with the 13836 Single UNIX Specification: 13837 * The [EFBIG] and [EIO] mandatory error conditions are added. System Interfaces, Issue 6 915 fputws( ) System Interfaces 13838 NAME 13839 fputws - put a wide-character string on a stream 13840 SYNOPSIS 13841 #include 13842 #include 13843 int fputws(const wchar_t *restrict ws, FILE *restrict stream); | 13844 DESCRIPTION | 13845 CX The functionality described on this reference page is aligned with the ISO C standard. Any 13846 conflict between the requirements described here and the ISO C standard is unintentional. This 13847 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 13848 The fputws( ) function shall write a character string corresponding to the (null-terminated) 13849 wide-character string pointed to by ws to the stream pointed to by stream. No character 13850 corresponding to the terminating null wide-character code shall be written. 13851 CX The st_ctime and st_mtime fields of the file shall be marked for update between the successful 13852 execution of fputws( ) and the next successful completion of a call to fflush( ) or fclose( ) on the 13853 same stream or a call to exit( ) or abort( ). 13854 RETURN VALUE 13855 Upon successful completion, fputws( ) shall return a non-negative number. Otherwise, it shall 13856 CX return -1, set an error indicator for the stream, and set errno to indicate the error. 13857 ERRORS 13858 Refer to fputwc( ). 13859 EXAMPLES 13860 None. 13861 APPLICATION USAGE 13862 The fputws( ) function does not append a character. 13863 RATIONALE 13864 None. 13865 FUTURE DIRECTIONS 13866 None. 13867 SEE ALSO 13868 fopen( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , | 13869 CHANGE HISTORY 13870 First released in Issue 4. Derived from the MSE working draft. | 13871 Issue 5 13872 The Optional Header (OH) marking is removed from . 13873 Issue 6 13874 Extensions beyond the ISO C standard are now marked. | 13875 The fputws( ) prototype is updated for alignment with the ISO/IEC 9899: 1999 standard. | 916 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fread( ) 13876 NAME 13877 fread - binary input 13878 SYNOPSIS 13879 #include 13880 size_t fread(void *restrict ptr, size_t size, size_t nitems, | 13881 FILE *restrict stream); | 13882 DESCRIPTION | 13883 CX The functionality described on this reference page is aligned with the ISO C standard. Any 13884 conflict between the requirements described here and the ISO C standard is unintentional. This 13885 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 13886 The fread( ) function shall read into the array pointed to by ptr up to nitems members whose size 13887 is specified by size in bytes, from the stream pointed to by stream. For each object, size calls are | 13888 made to the fgetc( ) function and the results stored, in the order read, in an array of unsigned | 13889 char exactly overlaying the object. The file position indicator for the stream (if defined) is | 13890 advanced by the number of bytes successfully read. If an error occurs, the resulting value of the | 13891 file position indicator for the stream is indeterminate. If a partial member is read, its value is | 13892 indeterminate. | 13893 CX The fread( ) function may mark the st_atime field of the file associated with stream for update. The 13894 st_atime field shall be marked for update by the first successful execution of fgetc( ), fgets( ), 13895 fgetwc( ), fgetws( ), fread( ), fscanf( ), getc( ), getchar( ), gets( ), or scanf( ) using stream that returns 13896 data not supplied by a prior call to ungetc( ) or ungetwc( ). 13897 RETURN VALUE 13898 Upon successful completion, fread( ) shall return the number of members successfully read 13899 which is less than nitems only if a read error or end-of-file is encountered. If size or nitems is 0, 13900 fread( ) shall return 0 and the contents of the array and the state of the stream remain unchanged. 13901 CX Otherwise, if a read error occurs, the error indicator for the stream shall be set, and errno shall be 13902 set to indicate the error. 13903 ERRORS 13904 Refer to fgetc( ). 13905 EXAMPLES 13906 Reading from a Stream 13907 The following example reads a single element from the fp stream into the array pointed to by buf. 13908 #include 13909 ... 13910 size_t bytes_read; 13911 char buf[100]; 13912 FILE *fp; 13913 ... 13914 bytes_read = fread(buf, sizeof(buf), 1, fp); 13915 ... 13916 APPLICATION USAGE 13917 The ferror( ) or feof( ) functions must be used to distinguish between an error condition and an 13918 end-of-file condition. 13919 Because of possible differences in member length and byte ordering, files written using fwrite( ) 13920 are application-dependent, and possibly cannot be read using fread( ) by a different application System Interfaces, Issue 6 917 fread( ) System Interfaces 13921 or by the same application on a different processor. 13922 RATIONALE 13923 None. 13924 FUTURE DIRECTIONS 13925 None. 13926 SEE ALSO 13927 feof( ), ferror( ), fgetc( ), fopen( ), getc( ), gets( ), scanf( ), the Base Definitions volume of | 13928 IEEE Std. 1003.1-200x, | 13929 CHANGE HISTORY 13930 First released in Issue 1. Derived from Issue 1 of the SVID. | 13931 Issue 4 13932 The list of functions that may cause the st_atime field to be updated is revised. 13933 The following change is incorporated for alignment with the ISO C standard: 13934 * In the RETURN VALUE section, the behavior if size or nitems is 0 is defined. 13935 Issue 6 13936 Extensions beyond the ISO C standard are now marked. | 13937 The following changes are made for alignment with the ISO/IEC 9899: 1999 standard: | 13938 * The fread( ) prototype is updated. || 13939 * The DESCRIPTION is updated to describe how the bytes from a call to fgetc( ) are stored. | 918 Technical Standard (2000) (Draft July 31, 2000) System Interfaces free( ) 13940 NAME 13941 free - free allocated memory 13942 SYNOPSIS 13943 #include 13944 void free(void *ptr); 13945 DESCRIPTION 13946 CX The functionality described on this reference page is aligned with the ISO C standard. Any 13947 conflict between the requirements described here and the ISO C standard is unintentional. This 13948 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 13949 The free( ) function shall cause the space pointed to by ptr to be deallocated; that is, made 13950 available for further allocation. If ptr is a null pointer, no action shall occur. Otherwise, if the 13951 argument does not match a pointer earlier returned by the calloc( ), malloc( ), posix_memalign( ), or | 13952 realloc( ) function, or if the space is deallocated by a call to free( ) or realloc( ), the behavior is 13953 undefined. 13954 Any use of a pointer that refers to freed space results in undefined behavior. | 13955 RETURN VALUE 13956 The free( ) function shall return no value. 13957 ERRORS 13958 No errors are defined. 13959 EXAMPLES 13960 None. 13961 APPLICATION USAGE 13962 There is now no requirement for the implementation to support the inclusion of . 13963 RATIONALE 13964 None. 13965 FUTURE DIRECTIONS 13966 None. 13967 SEE ALSO 13968 calloc( ), malloc( ), realloc( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 13969 CHANGE HISTORY 13970 First released in Issue 1. Derived from Issue 1 of the SVID. | 13971 Issue 4 13972 The APPLICATION USAGE section is changed to record that need no longer be 13973 supported on XSI-conformant systems. 13974 The following change is incorporated for alignment with the ISO C standard: 13975 * The DESCRIPTION now states that the behavior is undefined if any use is made of a pointer 13976 that refers to freed space. This was implied but not stated explicitly in Issue 3. 13977 Issue 4, Version 2 13978 The DESCRIPTION is updated for X/OPEN UNIX conformance to indicate that the free( ) 13979 function can also be used to free memory allocated by valloc( ). System Interfaces, Issue 6 919 free( ) System Interfaces 13980 Issue 6 13981 Reference to the valloc( ) function is removed. 920 Technical Standard (2000) (Draft July 31, 2000) System Interfaces freeaddrinfo( ) 13982 NAME 13983 freeaddrinfo, getaddrinfo - get address information 13984 SYNOPSIS 13985 #include 13986 #include 13987 void freeaddrinfo(struct addrinfo *ai); 13988 int getaddrinfo(const char *restrict nodename, const char *restrict servname,| 13989 const struct addrinfo *restrict hints, struct addrinfo **restrict res);| 13990 DESCRIPTION | 13991 The freeaddrinfo( ) function frees one or more addrinfo structures returned by getaddrinfo( ), along 13992 with any additional storage associated with those structures. If the ai_next field of the structure 13993 is not null, the entire list of structures is freed. The freeaddrinfo( ) function shall support the 13994 freeing of arbitrary sublists of an addrinfo list originally returned by getaddrinfo( ). 13995 The getaddrinfo( ) function shall translate the name of a service location (for example, a host 13996 name) and/or a service name and shall return a set of socket addresses and associated 13997 information to be used in creating a socket with which to address the specified service. 13998 The freeaddrinfo( ) and getaddrinfo( ) functions shall be thread-safe. 13999 The nodename and servname arguments are either null pointers or pointers to null-terminated 14000 strings. One or both of these two arguments shall be supplied by the application as a non-null 14001 pointer. 14002 The format of a valid name depends on the protocol family or families. If a specific family is not 14003 given and the name could be interpreted as valid within multiple supported families, the 14004 implementation shall attempt to resolve the name in all supported families and, in absence of | 14005 errors, one or more results shall be returned. | 14006 If the nodename argument is not null, it can be a descriptive name or can be an address string. If 14007 IP6 the specified address family is AF_INET, AF_INET6, or AF_UNSPEC, valid descriptive names 14008 include host names. If the specified address family is AF_INET or AF_UNSPEC, address strings 14009 using Internet standard dot notation as specified in inet_addr( ) are valid. 14010 IP6 If the specified address family is AF_INET6 or AF_UNSPEC, standard IPv6 text forms described 14011 in inet_ntop( ) are valid. | 14012 If nodename is not null, the requested service location is named by nodename; otherwise, the 14013 requested service location is local to the caller. 14014 If servname is null, the call shall return network-level addresses for the specified nodename. If 14015 servname is not null, it is a null-terminated character string identifying the requested service. This 14016 can be either a descriptive name or a numeric representation suitable for use with the address 14017 IP6 family or families. If the specified address family is AF_INET, AF_INET6, or AF_UNSPEC, the 14018 service can be specified as a string specifying a decimal port number. 14019 If the hints argument is not null, it refers to a structure containing input values that may direct 14020 the operation by providing options and by limiting the returned information to a specific socket 14021 type, address family and/or protocol. In this hints structure every member other than ai_flags, 14022 ai_family , ai_socktype, and ai_protocol shall be set to zero or a null pointer. A value of 14023 AF_UNSPEC for ai_family means that the caller shall accept any protocol family. A value of zero 14024 for ai_socktype means that the caller shall accept any socket type. A value of zero for ai_protocol 14025 means that the caller shall accept any protocol. If hints is a null pointer, the behavior shall be as if 14026 it referred to a structure containing the value zero for the ai_flags, ai_socktype, and ai_protocol 14027 fields, and AF_UNSPEC for the ai_family field. System Interfaces, Issue 6 921 freeaddrinfo( ) System Interfaces 14028 Notes: 14029 1. If the caller handles only TCP and not UDP, for example, then the ai_protocol 14030 member of the hints structure should be set to IPPROTO_TCP when 14031 getaddrinfo( ) is called. 14032 2. If the caller handles only IPv4 and not IPv6, then the ai_family member of the 14033 hints structure should be set to PF_INET when getaddrinfo( ) is called. 14034 The ai_flags field to which the hints parameter points shall be set to zero or be the bitwise- 14035 inclusive OR of one or more of the values AI_PASSIVE, AI_CANONNAME, and 14036 AI_NUMERICHOST. 14037 If the AI_PASSIVE flag is specified, the returned address information shall be suitable for use in 14038 binding a socket for accepting incoming connections for the specified service. In this case, if the 14039 nodename argument is null, then the IP address portion of the socket address structure shall be 14040 set to INADDR_ANY for an IPv4 address or IN6ADDR_ANY_INIT for an IPv6 address. If the 14041 AI_PASSIVE flag is not specified, the returned address information shall be suitable for a call to 14042 connect( ) (for a connection-mode protocol) or for a call to connect( ), sendto( ), or sendmsg( ) (for a 14043 connectionless protocol). In this case, if the nodename argument is null, then the IP address 14044 portion of the socket address structure shall be set to the loopback address. 14045 If the AI_CANONNAME flag is specified and the nodename argument is not null, the function 14046 attempts to determine the canonical name corresponding to nodename (for example, if nodename 14047 is an alias or shorthand notation for a complete name). 14048 If the AI_NUMERICHOST flag is specified, then a non-null nodename string supplied shall be a 14049 numeric host address string. Otherwise, an [EAI_NONAME] error is returned. This flag prevents 14050 any type of name resolution service (for example, the DNS) from being invoked. 14051 If the AI_NUMERICSERV flag is specified, then a non-null servname string supplied shall be a 14052 numeric port string. Otherwise, an [EAI_NONAME] error is returned. This flag prevents any 14053 type of name resolution service (for example, NIS+) from being invoked. 14054 The ai_socktype field to which argument hints points specifies the socket type for the service, as 14055 defined in socket( ). If a specific socket type is not given (for example, a value of zero) and the 14056 service name could be interpreted as valid with multiple supported socket types, the 14057 implementation shall attempt to resolve the service name for all supported socket types and, in 14058 the absence of errors, all possible results shall be returned. A non-zero socket type value shall | 14059 limit the returned information to values with the specified socket type. | 14060 If the ai_family field to which hints points has the value AF_UNSPEC, addresses are returned for 14061 use with any protocol family that can be used with the specified nodename and/or servname. 14062 Otherwise, addresses are returned for use only with the specified protocol family. If ai_family is 14063 not AF_UNSPEC and ai_protocol is not zero, then addresses are returned for use only with the 14064 specified protocol family and protocol; the value of ai_protocol is interpreted as in a call to the 14065 socket( ) function with the corresponding values of ai_family and ai_protocol . 14066 RETURN VALUE 14067 A zero return value for getaddrinfo( ) indicates successful completion; a non-zero return value 14068 indicates failure. The possible values for the failures are listed in the ERRORS section. 14069 Upon successful return of getaddrinfo( ), the location to which res points refers to a linked list of 14070 addrinfo structures, each of which specifies a socket address and information for use in creating 14071 a socket with which to use that socket address. The list shall include at least one addrinfo 14072 structure. The ai_next field of each structure contains a pointer to the next structure on the list, or 14073 a null pointer if it is the last structure on the list. Each structure on the list includes values for use 14074 with a call to the socket( ) function, and a socket address for use with the connect( ) function or, if 922 Technical Standard (2000) (Draft July 31, 2000) System Interfaces freeaddrinfo( ) 14075 the AI_PASSIVE flag was specified, for use with the bind( ) function. The fields ai_family , 14076 ai_socktype, and ai_protocol are usable as the arguments to the socket( ) function to create a socket 14077 suitable for use with the returned address. The fields ai_addr and ai_addrlen are usable as the 14078 arguments to the connect( ) or bind( ) functions with such a socket, according to the AI_PASSIVE 14079 flag. 14080 If nodename is not null, and if requested by the AI_CANONNAME flag, the ai_canonname field of 14081 the first returned addrinfo structure points to a null-terminated string containing the canonical 14082 name corresponding to the input nodename; if the canonical name is not available, then 14083 ai_canonname refers to the nodename argument or a string with the same contents. The contents of 14084 the ai_flags field of the returned structures are undefined. 14085 All fields in socket address structures returned by getaddrinfo( ) that are not filled in through an 14086 explicit argument (for example, sin6_flowinfo and sin_zero) shall be set to zero. 14087 Note: This makes it easier to compare socket address structures. 14088 ERRORS 14089 The getaddrinfo( ) function shall fail and return the corresponding value if: | 14090 [EAI_AGAIN] The name could not be resolved at this time. Future attempts may succeed. 14091 [EAI_BADFLAGS] 14092 The flags parameter had an invalid value. 14093 [EAI_FAIL] A non-recoverable error occurred when attempting to resolve the name. 14094 [EAI_FAMILY] The address family was not recognized. 14095 [EAI_MEMORY] There was a memory allocation failure when trying to allocate storage for the 14096 return value. 14097 [EAI_NONAME] The name does not resolve for the supplied parameters. 14098 Neither nodename nor servname were supplied. At least one of these shall be 14099 supplied. 14100 [EAI_SERVICE] The service passed was not recognized for the specified socket type. 14101 [EAI_SOCKTYPE] 14102 The intended socket type was not recognized. 14103 [EAI_SYSTEM] A system error occurred; the error code can be found in errno. 14104 EXAMPLES 14105 None. 14106 APPLICATION USAGE 14107 None. 14108 RATIONALE 14109 None. 14110 FUTURE DIRECTIONS 14111 None. 14112 SEE ALSO 14113 connect( ), gethostbyname( ), getipnodebyname( ), getnameinfo( ), getservbyname( ), socket( ), the Base | 14114 Definitions volume of IEEE Std. 1003.1-200x, , | System Interfaces, Issue 6 923 freeaddrinfo( ) System Interfaces 14115 CHANGE HISTORY 14116 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. | 14117 The restrict keyword is added to the getaddrinfo( ) prototype for alignment with the | 14118 ISO/IEC 9899: 1999 standard. | 924 Technical Standard (2000) (Draft July 31, 2000) System Interfaces freehostent( ) 14119 NAME 14120 freehostent - network host database functions 14121 SYNOPSIS 14122 #include 14123 void freehostent(struct hostent *ptr); 14124 DESCRIPTION 14125 Refer to endhostent( ). System Interfaces, Issue 6 925 freopen( ) System Interfaces 14126 NAME 14127 freopen - open a stream | 14128 SYNOPSIS 14129 #include 14130 FILE *freopen(const char *restrict filename, const char *restrict mode, | 14131 FILE *restrict stream); | 14132 DESCRIPTION | 14133 CX The functionality described on this reference page is aligned with the ISO C standard. Any 14134 conflict between the requirements described here and the ISO C standard is unintentional. This 14135 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 14136 The freopen( ) function shall first attempt to flush the stream and close any file descriptor 14137 associated with stream. Failure to flush or close the file successfully shall be ignored. The error 14138 and end-of-file indicators for the stream shall be cleared. 14139 The freopen( ) function shall open the file whose path name is the string pointed to by filename 14140 and associate the stream pointed to by stream with it. The mode argument shall be used just as in 14141 fopen( ). 14142 The original stream shall be closed regardless of whether the subsequent open succeeds. 14143 If filename is a null pointer, the freopen( ) function shall attempt to change the mode of the stream | 14144 to that specified by mode, as if the name of the file currently associated with the stream had been | 14145 used. It is implementation-defined which changes of mode are permitted (if any), and under | 14146 what circumstances. | 14147 XSI After a successful call to the freopen( ) function, the orientation of the stream shall be cleared, the | 14148 encoding rule shall be cleared, and the associated mbstate_t object shall be set to describe an 14149 initial conversion state. 14150 CX The largest value that can be represented correctly in an object of type off_t shall be established | 14151 as the offset maximum in the open file description. 14152 RETURN VALUE 14153 Upon successful completion, freopen( ) shall return the value of stream. Otherwise, a null pointer 14154 CX shall be returned, and errno shall be set to indicate the error. 14155 ERRORS 14156 The freopen( ) function shall fail if: 14157 CX [EACCES] Search permission is denied on a component of the path prefix, or the file | 14158 exists and the permissions specified by mode are denied, or the file does not 14159 exist and write permission is denied for the parent directory of the file to be 14160 created. 14161 CX [EINTR] A signal was caught during freopen( ). | 14162 CX [EISDIR] The named file is a directory and mode requires write access. | 14163 CX [ELOOP] A loop exists in symbolic links encountered during resolution of the path | 14164 argument. | 14165 CX [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. | 14166 CX [ENAMETOOLONG] | 14167 The length of the filename argument exceeds {PATH_MAX} or a path name | 14168 component is longer than {NAME_MAX}. | 926 Technical Standard (2000) (Draft July 31, 2000) System Interfaces freopen( ) 14169 CX [ENFILE] The maximum allowable number of files is currently open in the system. | 14170 CX [ENOENT] A component of filename does not name an existing file or filename is an empty | 14171 string. 14172 CX [ENOSPC] The directory or file system that would contain the new file cannot be | 14173 expanded, the file does not exist, and it was to be created. 14174 CX [ENOTDIR] A component of the path prefix is not a directory. | 14175 CX [ENXIO] The named file is a character special or block special file, and the device | 14176 associated with this special file does not exist. 14177 CX [EOVERFLOW] The named file is a regular file and the size of the file cannot be represented | 14178 correctly in an object of type off_t. 14179 CX [EROFS] The named file resides on a read-only file system and mode requires write | 14180 access. 14181 The freopen( ) function may fail if: 14182 CX [EINVAL] The value of the mode argument is not valid. | 14183 CX [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during | 14184 resolution of the path argument. | 14185 CX [ENAMETOOLONG] | 14186 Path name resolution of a symbolic link produced an intermediate result 14187 whose length exceeds {PATH_MAX}. 14188 CX [ENOMEM] Insufficient storage space is available. | 14189 CX [ENXIO] A request was made of a nonexistent device, or the request was outside the | 14190 capabilities of the device. 14191 CX [ETXTBSY] The file is a pure procedure (shared text) file that is being executed and mode | 14192 requires write access. 14193 EXAMPLES 14194 Directing Standard Output to a File 14195 The following example logs all standard output to the /tmp/logfile file. 14196 #include 14197 ... 14198 FILE *fp; 14199 ... 14200 fp = freopen ("/tmp/logfile", "a+", stdout); 14201 ... 14202 APPLICATION USAGE 14203 The freopen( ) function is typically used to attach the preopened streams associated with stdin, 14204 stdout, and stderr to other files. 14205 RATIONALE 14206 None. System Interfaces, Issue 6 927 freopen( ) System Interfaces 14207 FUTURE DIRECTIONS 14208 None. 14209 SEE ALSO 14210 fclose( ), fopen( ), fdopen( ), mbsinit( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 14211 14212 CHANGE HISTORY 14213 First released in Issue 1. Derived from Issue 1 of the SVID. | 14214 Issue 4 14215 In the DESCRIPTION, the word ``name'' is replaced by ``path name'', to make it clear that the 14216 function is not limited to accepting file names only. 14217 In the ERRORS section: 14218 * The description of the [EMFILE] error has been changed to refer to {OPEN_MAX} file 14219 descriptors rather than {FOPEN_MAX} file descriptors, directories, and message catalogs. 14220 * The errors [EINVAL], [ENOMEM], and [ETXTBSY] are marked as extensions. 14221 * The [ENXIO] error is added in the ``may fail'' section and marked as an extension. 14222 The following change is incorporated for alignment with the ISO C standard: 14223 * The type of arguments filename and mode are changed from char* to const char*. 14224 The following change is incorporated for alignment with the FIPS requirements: 14225 * In the ERRORS section, the condition whereby [ENAMETOOLONG] is returned if a path 14226 name component is larger that {NAME_MAX} is now defined as mandatory and marked as 14227 an extension. 14228 Issue 4, Version 2 14229 The ERRORS section is updated for X/OPEN UNIX conformance as follows: 14230 * It states that [ELOOP] is returned if too many symbolic links are encountered during path 14231 name resolution. 14232 * A second [ENAMETOOLONG] condition is defined that may report excessive length of an 14233 intermediate result of path name resolution of a symbolic link. 14234 Issue 5 14235 The DESCRIPTION is updated to indicate that the orientation of the stream is cleared and the 14236 conversion state of the stream is set to an initial conversion state by a successful call to the 14237 freopen( ) function. 14238 Large File Summit extensions are added. 14239 Issue 6 14240 Extensions beyond the ISO C standard are now marked. 14241 The following changes are made for alignment with the ISO POSIX-1: 1996 standard: 14242 * The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. 14243 This is since behavior may vary from one file system to another. 14244 The following new requirements on POSIX implementations derive from alignment with the 14245 Single UNIX Specification: 14246 * In the DESCRIPTION, text is added to indicate setting of the offset maximum in the open file 14247 description. This change is to support large files. 928 Technical Standard (2000) (Draft July 31, 2000) System Interfaces freopen( ) 14248 * In the ERRORS section, the [EOVERFLOW] condition is added. This change is to support 14249 large files. 14250 * The [ELOOP] mandatory error condition is added. 14251 * A second [ENAMETOOLONG] is added as an optional error condition. 14252 * The [EINVAL], [ENOMEM], [ENXIO], and [ETXTBSY] optional error conditions are added. 14253 The following changes are made for alignment with the ISO/IEC 9899: 1999 standard: | 14254 * The freopen( ) prototype is updated. | 14255 * The DESCRIPTION is updated. | 14256 The wording of the mandatory [ELOOP] error condition is updated, and a second optional | 14257 [ELOOP] error condition is added. | System Interfaces, Issue 6 929 frexp( ) System Interfaces 14258 NAME 14259 frexp, frexpf, frexpl - extract mantissa and exponent from a double precision number | 14260 SYNOPSIS 14261 #include 14262 double frexp(double num, int *exp); 14263 float frexpf(float value, int *exp); | 14264 long double frexpl(long double value, int *exp); | 14265 DESCRIPTION | 14266 CX The functionality described on this reference page is aligned with the ISO C standard. Any 14267 conflict between the requirements described here and the ISO C standard is unintentional. This 14268 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 14269 These functions breaks a floating-point number into a normalized fraction and an integral power | 14270 of 2. It stores the integer exponent in the int object pointed to by exp. | 14271 An application wishing to check for error situations should set errno to 0 before calling frexp( ). If 14272 errno is non-zero on return, or the return value is NaN, an error has occurred. 14273 RETURN VALUE 14274 These functions shall return the value x, such that x has a magnitude in the interval [1 2,1) or 0, | 14275 and num equals x times 2 raised to the power *exp. | 14276 If num is 0, both parts of the result shall be 0. 14277 XSI If num is NaN, NaN shall be returned, errno may be set to [EDOM], and the value of *exp shall be 14278 unspecified. | 14279 If num is ±Inf, num shall be returned, errno may be set to [EDOM], and the value of *exp shall be 14280 unspecified. 14281 ERRORS 14282 These functions may fail if: | 14283 XSI [EDOM] The value of num is NaN or ±Inf. | 14284 XSI No other errors shall occur. 14285 EXAMPLES 14286 None. 14287 APPLICATION USAGE 14288 None. 14289 RATIONALE 14290 None. 14291 FUTURE DIRECTIONS 14292 None. 14293 SEE ALSO 14294 isnan( ), ldexp( ), modf( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 14295 CHANGE HISTORY 14296 First released in Issue 1. Derived from Issue 1 of the SVID. | 930 Technical Standard (2000) (Draft July 31, 2000) System Interfaces frexp( ) 14297 Issue 4 14298 References to matherr( ) are removed. 14299 The name of the first argument is changed from value to num. 14300 The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 14301 ISO C standard and to rationalize error handling in the mathematics functions. 14302 The return value specified for [EDOM] is marked as an extension. 14303 Issue 5 14304 The DESCRIPTION is updated to indicate how an application should check for an error. This 14305 text was previously published in the APPLICATION USAGE section. | 14306 Issue 6 | 14307 The frexpf( ) and frexpl( ) functions are added for alignment with the ISO/IEC 9899: 1999 | 14308 standard. | System Interfaces, Issue 6 931 fscanf( ) System Interfaces 14309 NAME 14310 fscanf, scanf, sscanf - convert formatted input 14311 SYNOPSIS 14312 #include 14313 int fscanf(FILE *restrict stream, const char *restrict format, ... ); | 14314 int scanf(const char *restrict format, ... ); | 14315 int sscanf(const char *restrict s, const char *restrict format, ... ); | 14316 DESCRIPTION | 14317 CX The functionality described on this reference page is aligned with the ISO C standard. Any 14318 conflict between the requirements described here and the ISO C standard is unintentional. This 14319 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 14320 The fscanf( ) function reads from the named input stream. The scanf( ) function reads from the 14321 standard input stream stdin. The sscanf( ) function reads from the string s. Each function reads 14322 bytes, interprets them according to a format, and stores the results in its arguments. Each 14323 expects, as arguments, a control string format described below, and a set of pointer arguments 14324 indicating where the converted input should be stored. The result is undefined if there are 14325 insufficient arguments for the format. If the format is exhausted while arguments remain, the 14326 excess arguments are evaluated but are otherwise ignored. 14327 XSI Conversions can be applied to the nth argument after the format in the argument list, rather than 14328 to the next unused argument. In this case, the conversion character '%' (see below) is replaced 14329 by the sequence "%n$", where n is a decimal integer in the range [1,{NL_ARGMAX}]. This 14330 feature provides for the definition of format strings that select arguments in an order 14331 appropriate to specific languages. In format strings containing the "%n$" form of conversion 14332 specifications, it is unspecified whether numbered arguments in the argument list can be 14333 referenced from the format string more than once. 14334 The format can contain either form of a conversion specification-that is, '%' or "%n$"-but the 14335 two forms cannot normally be mixed within a single format string. The only exception to this is 14336 that "%%" or "%*" can be mixed with the "%n$" form. 14337 The fscanf( ) function in all its forms allows for detection of a language-dependent radix 14338 character in the input string. The radix character is defined in the program's locale (category 14339 LC_NUMERIC). In the POSIX locale, or in a locale where the radix character is not defined, the 14340 radix character defaults to a period ('.'). 14341 The format is a character string, beginning and ending in its initial shift state, if any, composed 14342 of zero or more directives. Each directive is composed of one of the following: one or more 14343 white-space characters (, , , , or characters); 14344 an ordinary character (neither '%' nor a white-space character); or a conversion specification. 14345 XSI Each conversion specification is introduced by the character '%' or the character sequence 14346 "%n$", after which the following appear in sequence: 14347 * An optional assignment-suppressing character '*'. 14348 * An optional non-zero decimal integer that specifies the maximum field width. 14349 * An option length modifier that specifies the size of the receiving object. | 14350 * A conversion character that specifies the type of conversion to be applied. The valid 14351 conversion characters are described below. 14352 The fscanf( ) functions execute each directive of the format in turn. If a directive fails, as detailed 14353 below, the function shall return. Failures are described as input failures (due to the 14354 unavailability of input bytes) or matching failures (due to inappropriate input). 932 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fscanf( ) 14355 A directive composed of one or more white-space characters is executed by reading input until 14356 no more valid input can be read, or up to the first byte which is not a white-space character, | 14357 which remains unread. | 14358 A directive that is an ordinary character is executed as follows: the next byte is read from the | 14359 input and compared with the byte that comprises the directive; if the comparison shows that 14360 they are not equivalent, the directive fails, and the differing and subsequent bytes remain | 14361 unread. Similarly, if end-of-file, an encoding error, or a read error prevents a character from | 14362 being read, the directive fails. | 14363 A directive that is a conversion specification defines a set of matching input sequences, as 14364 described below for each conversion character. A conversion specification is executed in the 14365 following steps: 14366 Input white-space characters (as specified by isspace( )) are skipped, unless the conversion 14367 specification includes a '[', c, C, or n conversion character. 14368 An item is read from the input, unless the conversion specification includes an n conversion 14369 character. An input item is defined as the longest sequence of input bytes (up to any specified 14370 maximum field width, which may be measured in characters or bytes dependent on the 14371 conversion character) which is an initial subsequence of a matching sequence. The first byte, if 14372 any, after the input item remains unread. If the length of the input item is 0, the execution of the 14373 conversion specification fails; this condition is a matching failure, unless end-of-file, an encoding 14374 error, or a read error prevented input from the stream, in which case it is an input failure. 14375 Except in the case of a '%' conversion character, the input item (or, in the case of a %n 14376 conversion specification, the count of input bytes) is converted to a type appropriate to the 14377 conversion character. If the input item is not a matching sequence, the execution of the 14378 conversion specification fails; this condition is a matching failure. Unless assignment 14379 suppression was indicated by a '*', the result of the conversion is placed in the object pointed 14380 to by the first argument following the format argument that has not already received a 14381 XSI conversion result if the conversion specification is introduced by '%', or in the nth argument if 14382 introduced by the character sequence "%n$". If this object does not have an appropriate type, or 14383 if the result of the conversion cannot be represented in the space provided, the behavior is 14384 undefined. 14385 The length modifiers and their meanings are: | 14386 hh Specifies that a following d, i, o, u, x, X, or n conversion specifier applies to an argument | 14387 with type pointer to signed char or unsigned char. | 14388 h Specifies that a following d, i, o, u, x, X, or n conversion specifier applies to an argument | 14389 with type pointer to short or unsigned short. | 14390 l (ell) Specifies that a following d, i, o, u, x, X, or n conversion specifier applies to an argument | 14391 with type pointer to long or unsigned long; that a following a, A, e, E, f, F, g, or G | 14392 conversion specifier applies to an argument with type pointer to double; or that a | 14393 following c, s, or '[' conversion specifier applies to an argument with type pointer to | 14394 wchar_t. | 14395 ll (ell-ell)Specifies that a following d, i, o, u, x, X, or n conversion specifier applies to an argument | 14396 with type pointer to long long or unsigned long long. | 14397 j Specifies that a following d, i, o, u, x, X, or n conversion specifier applies to an argument | 14398 with type pointer to intmax_t or uintmax_t. | 14399 z Specifies that a following d, i, o, u, x, X, or n conversion specifier applies to an argument | 14400 with type pointer to size_t or the corresponding signed integer type. | System Interfaces, Issue 6 933 fscanf( ) System Interfaces 14401 t Specifies that a following d, i, o, u, x, X, or n conversion specifier applies to an argument | 14402 with type pointer to ptrdiff_t or the corresponding unsigned type. | 14403 L Specifies that a following a, A, e, E, f, F, g, or G conversion specifier applies to an | 14404 argument with type pointer to long double. | 14405 If a length modifier appears with any conversion specifier other than as specified above, the | 14406 behavior is undefined. | 14407 The following conversion characters are valid: | 14408 d Matches an optionally signed decimal integer, whose format is the same as expected for 14409 the subject sequence of strtol( ) with the value 10 for the base argument. In the absence 14410 of a size modifier, the application shall ensure that the corresponding argument is a 14411 pointer to int. 14412 i Matches an optionally signed integer, whose format is the same as expected for the 14413 subject sequence of strtol( ) with 0 for the base argument. In the absence of a size 14414 modifier, the application shall ensure that the corresponding argument is a pointer to 14415 int. 14416 o Matches an optionally signed octal integer, whose format is the same as expected for 14417 the subject sequence of strtoul( ) with the value 8 for the base argument. In the absence 14418 of a size modifier, the application shall ensure that the corresponding argument is a 14419 pointer to unsigned. | 14420 u Matches an optionally signed decimal integer, whose format is the same as expected for 14421 the subject sequence of strtoul( ) with the value 10 for the base argument. In the absence 14422 of a size modifier, the application shall ensure that the corresponding argument is a 14423 pointer to unsigned. | 14424 x Matches an optionally signed hexadecimal integer, whose format is the same as 14425 expected for the subject sequence of strtoul( ) with the value 16 for the base argument. In 14426 the absence of a size modifier, the application shall ensure that the corresponding 14427 argument is a pointer to unsigned. | 14428 a, e, f, g Matches an optionally signed floating-point number, infinity, or NaN, whose format is | 14429 the same as expected for the subject sequence of strtod( ). In the absence of a size | 14430 modifier, the application shall ensure that the corresponding argument is a pointer to 14431 float. 14432 If the fprintf( ) family of functions generates character string representations for infinity | 14433 and NaN (a symbolic entity encoded in floating-point format) to support | 14434 IEEE Std. 754-1985, the fscanf( ) family of functions shall recognize them as input. | 14435 s Matches a sequence of bytes that are not white-space characters. The application shall 14436 ensure that the corresponding argument is a pointer to the initial byte of an array of 14437 char, signed char, or unsigned char large enough to accept the sequence and a 14438 terminating null character code, which shall be added automatically. 14439 If an l (ell) qualifier is present, the input is a sequence of characters that begins in the 14440 initial shift state. Each character is converted to a wide character as if by a call to the 14441 mbrtowc( ) function, with the conversion state described by an mbstate_t object 14442 initialized to zero before the first character is converted. The application shall ensure 14443 that the corresponding argument is a pointer to an array of wchar_t large enough to 14444 accept the sequence and the terminating null wide character, which shall be added 14445 automatically. 934 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fscanf( ) 14446 [ Matches a non-empty sequence of bytes from a set of expected bytes (the scanset). The 14447 normal skip over white-space characters is suppressed in this case. The application 14448 shall ensure that the corresponding argument is a pointer to the initial byte of an array 14449 of char, signed char, or unsigned char large enough to accept the sequence and a 14450 terminating null byte, which shall be added automatically. 14451 If an l (ell) qualifier is present, the input is a sequence of characters that begins in the 14452 initial shift state. Each character in the sequence is converted to a wide character as if 14453 by a call to the mbrtowc( ) function, with the conversion state described by an mbstate_t 14454 object initialized to zero before the first character is converted. The application shall 14455 ensure that the corresponding argument is a pointer to an array of wchar_t large 14456 enough to accept the sequence and the terminating null wide character, which shall be 14457 added automatically. 14458 The conversion specification includes all subsequent bytes in the format string up to 14459 and including the matching right square bracket (']'). The bytes between the square 14460 brackets (the scanlist) comprise the scanset, unless the byte after the left square bracket 14461 is a circumflex (' '), in which case the scanset contains all bytes that do not appear in 14462 the scanlist between the circumflex and the right square bracket. If the conversion 14463 specification begins with "[ ]" or "[ ]", the right square bracket is included in the 14464 scanlist and the next right square bracket is the matching right square bracket that ends 14465 the conversion specification; otherwise, the first right square bracket is the one that 14466 ends the conversion specification. If a '-' is in the scanlist and is not the first character, 14467 nor the second where the first character is a ' ', nor the last character, the behavior is | 14468 implementation-defined. | 14469 c Matches a sequence of bytes of the number specified by the field width (1 if no field 14470 width is present in the conversion specification). The application shall ensure that the 14471 corresponding argument is a pointer to the initial byte of an array of char, signed char, 14472 or unsigned char large enough to accept the sequence. No null byte is added. The 14473 normal skip over white-space characters is suppressed in this case. 14474 If an l (ell) qualifier is present, the input is a sequence of characters that begins in the 14475 initial shift state. Each character in the sequence is converted to a wide character as if 14476 by a call to the mbrtowc( ) function, with the conversion state described by an mbstate_t 14477 object initialized to zero before the first character is converted. The application shall 14478 ensure that the corresponding argument is a pointer to an array of wchar_t large 14479 enough to accept the resulting sequence of wide characters. No null wide character is 14480 added. 14481 p Matches an implementation-defined set of sequences, which shall be the same as the set | 14482 of sequences that is produced by the %p conversion of the corresponding fprintf( ) 14483 functions. The application shall ensure that the corresponding argument is a pointer to 14484 a pointer to void. The interpretation of the input item is implementation-defined. If the | 14485 input item is a value converted earlier during the same program execution, the pointer 14486 that results shall compare equal to that value; otherwise, the behavior of the %p 14487 conversion is undefined. 14488 n No input is consumed. The application shall ensure that the corresponding argument is 14489 a pointer to the integer into which is to be written the number of bytes read from the 14490 input so far by this call to the fscanf( ) functions. Execution of a %n conversion 14491 specification does not increment the assignment count returned at the completion of 14492 execution of the function. No argument is converted, but one is consumed. If the | 14493 conversion specification includes an assignment-suppressing character or a field width, | 14494 the behavior is undefined. | System Interfaces, Issue 6 935 fscanf( ) System Interfaces 14495 XSI C Same as lc. 14496 XSI S Same as ls. 14497 % Matches a single '%'; no conversion or assignment occurs. The complete conversion 14498 specification shall be "%%". 14499 If a conversion specification is invalid, the behavior is undefined. 14500 The conversion characters A, E, F, G, and X are also valid and behave the same as, respectively, a, | 14501 e, f, g, and x. | 14502 If end-of-file is encountered during input, conversion is terminated. If end-of-file occurs before 14503 any bytes matching the current conversion specification (except for %n) have been read (other 14504 than leading white-space characters, where permitted), execution of the current conversion 14505 specification terminates with an input failure. Otherwise, unless execution of the current 14506 conversion specification is terminated with a matching failure, execution of the following 14507 conversion specification (if any) is terminated with an input failure. 14508 Reaching the end of the string in sscanf( ) is equivalent to encountering end-of-file for fscanf( ). 14509 If conversion terminates on a conflicting input, the offending input is left unread in the input. 14510 Any trailing white space (including newline characters) is left unread unless matched by a 14511 conversion specification. The success of literal matches and suppressed assignments is only 14512 directly determinable via the %n conversion specification. 14513 The fscanf( ) and scanf( ) functions may mark the st_atime field of the file associated with stream 14514 for update. The st_atime field shall be marked for update by the first successful execution of 14515 fgetc( ), fgets( ), fread( ), getc( ), getchar( ), gets( ), fscanf( ), or fscanf( ) using stream that returns data 14516 not supplied by a prior call to ungetc( ). 14517 RETURN VALUE 14518 Upon successful completion, these functions shall return the number of successfully matched 14519 and assigned input items; this number can be 0 in the event of an early matching failure. If the 14520 input ends before the first matching failure or conversion, EOF shall be returned. If a read error 14521 CX occurs, the error indicator for the stream is set, EOF shall be returned, and errno shall be set to 14522 indicate the error. 14523 ERRORS 14524 For the conditions under which the fscanf( ) functions fail and may fail, refer to fgetc( ) or 14525 fgetwc( ). 14526 In addition, fscanf( ) may fail if: 14527 XSI [EILSEQ] Input byte sequence does not form a valid character. | 14528 XSI [EINVAL] There are insufficient arguments. | 14529 EXAMPLES 14530 The call: 14531 int i, n; float x; char name[50]; 14532 n = scanf("%d%f%s", &i, &x, name); 14533 with the input line: 14534 25 54.32E-1 Hamster 14535 assigns to n the value 3, to i the value 25, to x the value 5.432, and name contains the string 14536 "Hamster". 936 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fscanf( ) 14537 The call: 14538 int i; float x; char name[50]; 14539 (void) scanf("%2d%f%*d %[0123456789]", &i, &x, name); 14540 with input: 14541 56789 0123 56a72 14542 assigns 56 to i, 789.0 to x, skips 0123, and places the string "56\0" in name. The next call to 14543 getchar( ) shall return the character 'a'. 14544 Reading Data into an Array 14545 The following call uses fscanf( ) to read three floating point numbers from standard input into 14546 the input array. 14547 float input[3]; 14548 fscanf (stdin, "%f %f %f", input, input+1, input+2); 14549 APPLICATION USAGE 14550 If the application calling fscanf( ) has any objects of type wint_t or wchar_t, it must also include 14551 the header to have these objects defined. 14552 RATIONALE 14553 None. 14554 FUTURE DIRECTIONS 14555 None. 14556 SEE ALSO 14557 getc( ), printf( ), setlocale( ), strtod( ), strtol( ), strtoul( ), wcrtomb( ), the Base Definitions volume of | 14558 IEEE Std. 1003.1-200x, , , , the Base Definitions volume of | 14559 IEEE Std. 1003.1-200x, Chapter 7, Locale | 14560 CHANGE HISTORY 14561 First released in Issue 1. Derived from Issue 1 of the SVID. | 14562 Issue 4 14563 Use of the terms ``byte'' and ``character'' is rationalized to make it clear when single-byte and 14564 multi-byte values can be used. Similarly, use of the terms ``conversion specification'' and 14565 ``conversion character'' is now more precise. 14566 Various errors are corrected. For example, the description of the d conversion character 14567 contained an erroneous reference to strtod( ) in Issue 3. This is replaced in this issue by reference 14568 to strtol( ). 14569 The DESCRIPTION is updated in a number of places to indicate further implications of the 14570 "%n$" form of a conversion. All references to this functionality, which is not specified in the 14571 ISO C standard, are marked as extensions. 14572 The ERRORS section is changed to refer to the entries for fgetc( ) and fgetwc( ), the [EINVAL] 14573 error is marked as an extension, and the [EILSEQ] error is added and marked as an extension. 14574 The detailed description of this function including the CHANGE HISTORY section for scanf( ) is 14575 provided here instead of under scanf( ). 14576 The APPLICATION USAGE section is amended to record the need for or 14577 if type wchar_t is required. System Interfaces, Issue 6 937 fscanf( ) System Interfaces 14578 The following changes are incorporated for alignment with the ISO C standard: 14579 * The type of the argument format for all functions, and the type of argument s for sscanf( ), are 14580 changed from char* to const char*. 14581 * The description is updated in various places to align more closely with the text of the ISO C 14582 standard. In particular, this issue fully defines the L conversion character, allows for the 14583 support of multi-byte coded character sets (although these are not mandated by X/Open), 14584 and fills in a number of gaps in the definition (for example, by defining termination 14585 conditions for sscanf( ). 14586 * Following an ANSI interpretation, the effect of conversion specifications that consume no 14587 input is better defined, and is no longer marked as an extension. 14588 The following change is incorporated for alignment with the MSE working draft. 14589 * The C and S conversion characters are added, indicating a pointer in the argument list to the 14590 initial wide-character code of an array large enough to accept the input sequence. 14591 Issue 5 14592 Aligned with ISO/IEC 9899: 1990/Amendment 1: 1995 (E). Specifically, the l (ell) qualifier is now 14593 defined for the c, s, and '[' conversion characters. 14594 The DESCRIPTION is updated to indicate that if infinity and NaN can be generated by the 14595 fprintf( ) family of functions, then they are recognized by the fscanf( ) family. 14596 Issue 6 14597 The Open Group corrigenda items U021/7 and U028/10 have been applied. These correct 14598 several occurrences of ``characters'' in the text which have been replaced with the term ``bytes''. 14599 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. | 14600 The following changes are made for alignment with the ISO/IEC 9899: 1999 standard: | 14601 * The prototypes for fscanf( ), scanf( ), and sscanf( ) are updated. || 14602 * The DESCRIPTION is updated. | 938 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fseek( ) 14603 NAME 14604 fseek, fseeko - reposition a file-position indicator in a stream 14605 SYNOPSIS 14606 #include 14607 int fseek(FILE *stream, long offset, int whence); | 14608 CX int fseeko(FILE *stream, off_t offset, int whence); | 14609 14610 DESCRIPTION 14611 CX The functionality described on this reference page is aligned with the ISO C standard. Any 14612 conflict between the requirements described here and the ISO C standard is unintentional. This 14613 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 14614 The fseek( ) function shall set the file-position indicator for the stream pointed to by stream. If a | 14615 read or write error occurs, the error indicator for the stream shall be set and fseek( ) fails. | 14616 The new position, measured in bytes from the beginning of the file, shall be obtained by adding 14617 offset to the position specified by whence. The specified point is the beginning of the file for 14618 {SEEK_SET}, the current value of the file-position indicator for {SEEK_CUR}, or end-of-file for 14619 {SEEK_END}. 14620 If the stream is to be used with wide-character input/output functions, the application shall 14621 ensure that offset is either 0 or a value returned by an earlier call to ftell( ) on the same stream and 14622 whence is {SEEK_SET}. 14623 A successful call to fseek( ) shall clear the end-of-file indicator for the stream and undo any effects 14624 of ungetc( ) and ungetwc( ) on the same stream. After an fseek( ) call, the next operation on an 14625 update stream may be either input or output. 14626 If the most recent operation, other than ftell( ), on a given stream is fflush( ), the file offset in the 14627 underlying open file description shall be adjusted to reflect the location specified by fseek( ). 14628 The fseek( ) function shall allow the file-position indicator to be set beyond the end of existing 14629 data in the file. If data is later written at this point, subsequent reads of data in the gap shall 14630 return bytes with the value 0 until data is actually written into the gap. 14631 CX The behavior of fseek( ) on devices which are incapable of seeking is implementation-defined. | 14632 The value of the file offset associated with such a device is undefined. 14633 If the stream is writable and buffered data had not been written to the underlying file, fseek( ) 14634 shall cause the unwritten data to be written to the file and shall mark the st_ctime and st_mtime 14635 fields of the file for update. 14636 In a locale with state-dependent encoding, whether fseek( ) restores the stream's shift state is | 14637 implementation-defined. | 14638 The fseeko( ) function is equivalent to the fseek( ) function except that the offset argument is of | 14639 type off_t. 14640 RETURN VALUE 14641 CX The fseek( ) and fseeko( )functions shall return 0 if they succeed. 14642 CX Otherwise, they shall return -1 and set errno to indicate the error. 14643 ERRORS 14644 CX The fseek( ) and fseeko( ) functions shall fail if, either the stream is unbuffered or the stream's 14645 CX buffer needed to be flushed, and the call to fseek( ) or fseeko( ) causes an underlying lseek( ) or 14646 write( ) to be invoked: System Interfaces, Issue 6 939 fseek( ) System Interfaces 14647 CX [EAGAIN] The O_NONBLOCK flag is set for the file descriptor and the process would be | 14648 delayed in the write operation. 14649 CX [EBADF] The file descriptor underlying the stream file is not open for writing or the | 14650 stream's buffer needed to be flushed and the file is not open. 14651 CX [EFBIG] An attempt was made to write a file that exceeds the maximum file size. | 14652 XSI [EFBIG] An attempt was made to write a file that exceeds the process' file size limit. | 14653 CX [EFBIG] The file is a regular file and an attempt was made to write at or beyond the | 14654 offset maximum associated with the corresponding stream. 14655 CX [EINTR] The write operation was terminated due to the receipt of a signal, and no data | 14656 was transferred. 14657 CX [EINVAL] The whence argument is invalid. The resulting file-position indicator would be | 14658 set to a negative value. 14659 CX [EIO] A physical I/O error has occurred, or the process is a member of a | 14660 background process group attempting to perform a write( ) to its controlling 14661 terminal, TOSTOP is set, the process is neither ignoring nor blocking 14662 SIGTTOU, and the process group of the process is orphaned. This error may 14663 also be returned under implementation-defined conditions. | 14664 CX [ENOSPC] There was no free space remaining on the device containing the file. | 14665 CX [EOVERFLOW] For fseek( ), the resulting file offset would be a value which cannot be | 14666 represented correctly in an object of type long. 14667 CX [EOVERFLOW] For fseeko( ), the resulting file offset would be a value which cannot be | 14668 represented correctly in an object of type off_t. 14669 CX [EPIPE] The file descriptor underlying stream is associated with a pipe or FIFO. | 14670 CX [EPIPE] An attempt was made to write to a pipe or FIFO that is not open for reading | 14671 by any process; a SIGPIPE signal shall also be sent to the thread. 14672 CX [ENXIO] A request was made of a nonexistent device, or the request was outside the | 14673 capabilities of the device. 14674 EXAMPLES 14675 None. 14676 APPLICATION USAGE 14677 None. 14678 RATIONALE 14679 None. 14680 FUTURE DIRECTIONS 14681 None. 14682 SEE ALSO 14683 fopen( ), fsetpos( ), ftell( ), getrlimit( ), rewind( ), ulimit( ), ungetc( ), the Base Definitions volume of | 14684 IEEE Std. 1003.1-200x, | 14685 CHANGE HISTORY 14686 First released in Issue 1. Derived from Issue 1 of the SVID. | 940 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fseek( ) 14687 Issue 4 14688 In the DESCRIPTION, the words ``The seek( ) function does not, by itself, extend the size of a 14689 file'' are deleted. 14690 In the RETURN VALUE section, the value -1 is marked as an extension. This is because the 14691 ISO POSIX-1 standard only requires that a non-zero value is returned. 14692 In the ERRORS section, text is added to indicate that error returns are only generated when 14693 either the stream is unbuffered, or if the stream buffer needs to be flushed. 14694 The ``fail'' and ``may fail'' parts of the ERRORS section are revised for consistency with lseek( ) 14695 and write( ). 14696 Text associated with the [EIO] error is expanded and the [ENXIO] error is added. 14697 Text is added to explain how fseek( ) is used with wide-character input/output; this is marked as 14698 a WP extension. 14699 The [EFBIG] error is marked to show extensions. 14700 The APPLICATION USAGE section is added. 14701 The following change is incorporated for alignment with the ISO C standard: 14702 * The type of argument offset is now defined in full as long instead of long. | 14703 The following change is incorporated for alignment with the FIPS requirements: 14704 * The [EINTR] error is no longer an indication that the implementation does not report partial 14705 transfers. 14706 Issue 4, Version 2 14707 In the ERRORS section, the description of [EIO] is updated to include the case where a physical 14708 I/O error occurs. 14709 Issue 5 14710 Normative text previously in the APPLICATION USAGE section is moved to the 14711 DESCRIPTION. 14712 Large File Summit extensions are added. 14713 Issue 6 14714 Extensions beyond the ISO C standard are now marked. 14715 The following new requirements on POSIX implementations derive from alignment with the 14716 Single UNIX Specification: 14717 * The fseeko( ) function is added. 14718 * The [EFBIG], [EOVERFLOW], and [ENXIO] mandatory error conditions are added. 14719 The following change is incorporated for alignment with the FIPS requirements: 14720 * The [EINTR] error is no longer an indication that the implementation does not report partial 14721 transfers. 14722 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. | 14723 The DESCRIPTION is updated to explicitly state that fseek( ) sets the file-position indicator, and | 14724 then on error the error indicator is set and fseek( ) fails. This is for alignment with the | 14725 ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 941 fsetpos( ) System Interfaces 14726 NAME 14727 fsetpos - set current file position 14728 SYNOPSIS 14729 #include 14730 int fsetpos(FILE *stream, const fpos_t *pos); 14731 DESCRIPTION 14732 CX The functionality described on this reference page is aligned with the ISO C standard. Any 14733 conflict between the requirements described here and the ISO C standard is unintentional. This 14734 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 14735 The fsetpos( ) function shall set the file position and state indicators for the stream pointed to by 14736 stream according to the value of the object pointed to by pos, which the application shall ensure 14737 is a value obtained from an earlier call to fgetpos( ) on the same stream. If a read or write error | 14738 occurs, the error indicator for the stream shall be set and fsetpos( ) fails. | 14739 A successful call to the fsetpos( ) function shall clear the end-of-file indicator for the stream and 14740 undo any effects of ungetc( ) on the same stream. After an fsetpos( ) call, the next operation on an 14741 update stream may be either input or output. | 14742 CX The behavior of fsetpos( ) on devices which are incapable of seeking is implementation-defined. | 14743 The value of the file offset associated with such a device is undefined. | 14744 RETURN VALUE 14745 The fsetpos( ) function shall return 0 if it succeeds; otherwise, it shall return a non-zero value and 14746 set errno to indicate the error. 14747 ERRORS 14748 The fsetpos( ) function may fail if: 14749 CX [EBADF] The file descriptor underlying stream is not valid. | 14750 CX [ESPIPE] The file descriptor underlying stream is associated with a pipe, FIFO, or socket. | 14751 14752 EXAMPLES 14753 None. 14754 APPLICATION USAGE 14755 None. 14756 RATIONALE 14757 None. 14758 FUTURE DIRECTIONS 14759 None. 14760 SEE ALSO 14761 fopen( ), ftell( ), rewind( ), ungetc( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 14762 14763 CHANGE HISTORY 14764 First released in Issue 4. Derived from the ISO C standard. | 14765 Issue 6 14766 Extensions beyond the ISO C standard are now marked. 14767 An additional [ESPIPE] error condition is added for sockets. 942 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fsetpos( ) 14768 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. | 14769 The DESCRIPTION is updated to clarify that the error indicator is set for the stream on a read or | 14770 write error. This is for alignment with the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 943 fstat( ) System Interfaces 14771 NAME 14772 fstat - get file status 14773 SYNOPSIS 14774 #include 14775 int fstat(int fildes, struct stat *buf); 14776 DESCRIPTION 14777 The fstat( ) function obtains information about an open file associated with the file descriptor 14778 fildes, and writes it to the area pointed to by buf. 14779 SHM If fildes references a shared memory object, the implementation need update in the stat structure 14780 pointed to by the buf argument only the st_uid, st_gid, st_size, and st_mode fields, and only the 14781 S_IRUSR, S_IWUSR, S_IRGRP, S_IWGRP, S_IROTH, and S_IWOTH file permission bits need be 14782 valid. 14783 TYM If fildes references a typed memory object, the implementation need update in the stat structure 14784 pointed to by the buf argument only the st_uid, st_gid, st_size, and st_mode fields, and only the 14785 S_IRUSR, S_IWUSR, S_IRGRP, S_IWGRP, S_IROTH, and S_IWOTH file permission bits need be 14786 valid. 14787 The buf argument is a pointer to a stat structure, as defined in , into which 14788 information is placed concerning the file. 14789 The structure members st_mode, st_ino, st_dev, st_uid, st_gid, st_atime, st_ctime, and st_mtime 14790 shall have meaningful values for all file types defined in this volume of IEEE Std. 1003.1-200x. 14791 The value of the member st_nlink shall be set to the number of links to the file. 14792 An implementation that provides additional or alternative file access control mechanisms may, | 14793 under implementation-defined conditions, cause fstat( ) to fail. | 14794 The fstat( ) function updates any time-related fields as described in File Times Update (see the | 14795 Base Definitions volume of IEEE Std. 1003.1-200x, Chapter 6, Character Set), before writing into | 14796 the stat structure. | 14797 RETURN VALUE 14798 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno set to 14799 indicate the error. 14800 ERRORS 14801 The fstat( ) function shall fail if: 14802 [EBADF] The fildes argument is not a valid file descriptor. | 14803 [EIO] An I/O error occurred while reading from the file system. | 14804 [EOVERFLOW] The file size in bytes or the number of blocks allocated to the file or the file | 14805 serial number cannot be represented correctly in the structure pointed to by 14806 buf. | 14807 The fstat( ) function may fail if: 14808 [EOVERFLOW] One of the values is too large to store into the structure pointed to by the buf | 14809 argument. | 944 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fstat( ) 14810 EXAMPLES 14811 Obtaining File Status Information 14812 The following example shows how to obtain file status information for a file named 14813 /home/cnd/mod1. The structure variable buffer is defined for the stat structure. The 14814 /home/cnd/mod1 file is opened with read/write privileges and is passed to the open file 14815 descriptor fildes. 14816 #include 14817 #include 14818 #include 14819 struct stat buffer; 14820 int status; 14821 ... 14822 fildes = open("/home/cnd/mod1", O_RDWR); 14823 status = fstat(fildes, &buffer); 14824 APPLICATION USAGE 14825 None. 14826 RATIONALE 14827 None. 14828 FUTURE DIRECTIONS 14829 None. 14830 SEE ALSO 14831 lstat( ), stat( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , | 14832 CHANGE HISTORY 14833 First released in Issue 1. Derived from Issue 1 of the SVID. | 14834 Issue 4 14835 The header is now marked as optional (OH); this header need not be included on 14836 XSI-conformant systems. 14837 The following changes are incorporated in the DESCRIPTION for alignment with the 14838 ISO POSIX-1 standard: 14839 * A paragraph defining the contents of stat structure members is added. 14840 * The words ``extended security controls'' are replaced by ``additional or alternative file access 14841 control mechanisms''. 14842 Issue 4, Version 2 14843 The ERRORS section is updated for X/OPEN UNIX conformance as follows: 14844 * The [EIO] error is added as a mandatory error indicated the occurrence of an I/O error. 14845 * The [EOVERFLOW] error is added as an optional error indicating that one of the values is 14846 too large to store in the area pointed to by buf. 14847 Issue 5 14848 The DESCRIPTION is updated for alignment with the POSIX Realtime Extension. 14849 Large File Summit extensions are added. System Interfaces, Issue 6 945 fstat( ) System Interfaces 14850 Issue 6 14851 In the SYNOPSIS, the inclusion of is no longer required. 14852 The following new requirements on POSIX implementations derive from alignment with the 14853 Single UNIX Specification: 14854 * The requirement to include has been removed. Although was 14855 required for conforming implementations of previous POSIX specifications, it was not 14856 required for UNIX applications. 14857 * The [EIO] mandatory error condition is added. 14858 * The [EOVERFLOW] mandatory error condition is added. This change is to support large 14859 files. 14860 * The [EOVERFLOW] optional error condition is added. 14861 The DESCRIPTION is updated for alignment with IEEE Std. 1003.1j-2000 by specifying that 14862 shared memory object semantics apply to typed memory objects. 946 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fstatvfs( ) 14863 NAME 14864 fstatvfs, statvfs - get file system information 14865 SYNOPSIS 14866 XSI #include 14867 int fstatvfs(int fildes, struct statvfs *buf); 14868 int statvfs(const char *restrict path, struct statvfs *restrict buf); | 14869 | 14870 DESCRIPTION 14871 The fstatvfs( ) function obtains information about the file system containing the file referenced by 14872 fildes. 14873 The following flags can be returned in the f_flag member: | 14874 ST_RDONLY Read-only file system. 14875 ST_NOSUID Setuid/setgid bits ignored by exec. 14876 The statvfs( ) function obtains descriptive information about the file system containing the file 14877 named by path. 14878 For both functions, the buf argument is a pointer to a statvfs structure that shall be filled. Read, 14879 write, or execute permission of the named file is not required. | 14880 It is unspecified whether all members of the statvfs structure have meaningful values on all file 14881 systems. 14882 RETURN VALUE 14883 Upon successful completion, statvfs( ) shall return 0. Otherwise, it shall return -1 and set errno to 14884 indicate the error. 14885 ERRORS 14886 The fstatvfs( ) and statvfs( ) functions shall fail if: 14887 [EIO] An I/O error occurred while reading the file system. | 14888 [EINTR] A signal was caught during execution of the function. | 14889 [EOVERFLOW] One of the values to be returned cannot be represented correctly in the | 14890 structure pointed to by buf. 14891 The fstatvfs( ) function shall fail if: 14892 [EBADF] The fildes argument is not an open file descriptor. | 14893 The statvfs( ) function shall fail if: 14894 [EACCES] Search permission is denied on a component of the path prefix. | 14895 [ELOOP] A loop exists in symbolic links encountered during resolution of the path | 14896 argument. | 14897 [ENAMETOOLONG] | 14898 The length of a path name exceeds {PATH_MAX} or a path name component | 14899 is longer than {NAME_MAX}. 14900 [ENOENT] A component of path does not name an existing file or path is an empty string. | 14901 [ENOTDIR] A component of the path prefix of path is not a directory. | 14902 The statvfs( ) function may fail if: System Interfaces, Issue 6 947 fstatvfs( ) System Interfaces 14903 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during | 14904 resolution of the path argument. | 14905 [ENAMETOOLONG] | 14906 Path name resolution of a symbolic link produced an intermediate result 14907 whose length exceeds {PATH_MAX}. 14908 EXAMPLES 14909 Obtaining File System Information Using fstatvfs( ) 14910 The following example shows how to obtain file system information for the file system upon 14911 which the file named /home/cnd/mod1 resides, using the fstatvfs( ) function. The 14912 /home/cnd/mod1 file is opened with read/write privileges and the open file descriptor is passed 14913 to the fstatvfs( ) function. 14914 #include 14915 #include 14916 struct statvfs buffer; 14917 int status; 14918 ... 14919 fildes = open("/home/cnd/mod1", O_RDWR); 14920 status = fstatvfs(fildes, &buffer); 14921 Obtaining File System Information Using statvfs( ) 14922 The following example shows how to obtain file system information for the file system upon 14923 which the file named /home/cnd/mod1 resides, using the statvfs( ) function. 14924 #include 14925 struct statvfs buffer; 14926 int status; 14927 ... 14928 status = statvfs("/home/cnd/mod1", &buffer); 14929 APPLICATION USAGE 14930 None. 14931 RATIONALE 14932 None. 14933 FUTURE DIRECTIONS 14934 None. 14935 SEE ALSO 14936 chmod( ), chown( ), creat( ), dup( ), exec, fcntl( ), link( ), mknod( ), open( ), pipe( ), read( ), time( ), 14937 unlink( ), utime( ), write( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 14938 CHANGE HISTORY 14939 First released in Issue 4, Version 2. 14940 Issue 5 14941 Moved from X/OPEN UNIX extension to BASE. 14942 Large File Summit extensions are added. 948 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fstatvfs( ) 14943 Issue 6 14944 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. | 14945 The restrict keyword is added to the statvfs( ) prototype for alignment with the | 14946 ISO/IEC 9899: 1999 standard. | 14947 The wording of the mandatory [ELOOP] error condition is updated, and a second optional | 14948 [ELOOP] error condition is added. | System Interfaces, Issue 6 949 fsync( ) System Interfaces 14949 NAME 14950 fsync - synchronize changes to a file 14951 SYNOPSIS 14952 FSC #include 14953 int fsync(int fildes); 14954 14955 DESCRIPTION 14956 The fsync( ) function can be used by an application to indicate that all data for the open file 14957 description named by fildes is to be transferred to the storage device associated with the file 14958 described by fildes in an implementation-defined manner. The fsync( ) function shall not return | 14959 until the system has completed that action or until an error is detected. 14960 SIO If _POSIX_SYNCHRONIZED_IO is defined, the fsync( ) function shall force all currently queued 14961 I/O operations associated with the file indicated by file descriptor fildes to the synchronized I/O 14962 completion state. All I/O operations shall be completed as defined for synchronized I/O file 14963 integrity completion. 14964 RETURN VALUE 14965 Upon successful completion, fsync( ) shall return 0. Otherwise, -1 shall be returned and errno set 14966 to indicate the error. If the fsync( ) function fails, outstanding I/O operations are not guaranteed 14967 to have been completed. 14968 ERRORS 14969 The fsync( ) function shall fail if: 14970 [EBADF] The fildes argument is not a valid descriptor. | 14971 [EINTR] The fsync( ) function was interrupted by a signal. | 14972 [EINVAL] The fildes argument does not refer to a file on which this operation is possible. | 14973 [EIO] An I/O error occurred while reading from or writing to the file system. | 14974 In the event that any of the queued I/O operations fail, fsync( ) shall return the error conditions 14975 defined for read( ) and write( ). 14976 EXAMPLES 14977 None. 14978 APPLICATION USAGE 14979 The fsync( ) function should be used by programs which require modifications to a file to be 14980 completed before continuing; for example, a program which contains a simple transaction 14981 facility might use it to ensure that all modifications to a file or files caused by a transaction are 14982 recorded. 14983 RATIONALE 14984 The fsync( ) function is intended to force a physical write of data from the buffer cache, and to 14985 assure that after a system crash or other failure that all data up to the time of the fsync( ) call is 14986 recorded on the disk. Since the concepts of ``buffer cache'', ``system crash'', ``physical write'', and 14987 ``non-volatile storage'' are not defined here, the wording has to be more abstract. 14988 If _POSIX_SYNCHRONIZED_IO is not defined, the wording relies heavily on the conformance 14989 document to tell the user what can be expected from the system. It is explicitly intended that a 14990 null implementation is permitted. This could be valid in the case where the system cannot assure 14991 non-volatile storage under any circumstances or when the system is highly fault-tolerant and the 14992 functionality is not required. In the middle ground between these extremes, fsync( ) might or 14993 might not actually cause data to be written where it is safe from a power failure. The 950 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fsync( ) 14994 conformance document should identify at least that one configuration exists (and how to obtain 14995 that configuration) where this can be assured for at least some files that the user can select to use 14996 for critical data. It is not intended that an exhaustive list is required, but rather sufficient 14997 information is provided to let the user determine that if he or she has critical data he or she can 14998 configure her system to allow it to be written to non-volatile storage. 14999 It is reasonable to assert that the key aspects of fsync( ) are unreasonable to test in a test suite. 15000 That does not make the function any less valuable, just more difficult to test. A formal 15001 conformance test should probably force a system crash (power shutdown) during the test for 15002 this condition, but it needs to be done in such a way that automated testing does not require this 15003 to be done except when a formal record of the results is being made. It would also not be 15004 unreasonable to omit testing for fsync( ), allowing it to be treated as a quality-of-implementation 15005 issue. 15006 FUTURE DIRECTIONS 15007 None. 15008 SEE ALSO 15009 sync( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 15010 CHANGE HISTORY 15011 First released in Issue 3. 15012 Issue 4 15013 The header is added to the SYNOPSIS section. 15014 In the APPLICATION USAGE section, the words ``require a file to be in a known state'' are 15015 replaced by ``require modifications to a file to be completed before continuing''. 15016 Issue 5 15017 Aligned with fsync( ) in the POSIX Realtime Extension. Specifically, the DESCRIPTION and 15018 RETURN VALUE sections are much expanded, and the ERRORS section is updated to indicate 15019 that fsync( ) can return the error conditions defined for read( ) and write( ). 15020 Issue 6 15021 This function is marked as part of the File Synchronization option. | 15022 The following new requirements on POSIX implementations derive from alignment with the 15023 Single UNIX Specification: 15024 * The [EINVAL] and [EIO] mandatory error conditions are added. System Interfaces, Issue 6 951 ftell( ) System Interfaces 15025 NAME 15026 ftell, ftello - return a file offset in a stream 15027 SYNOPSIS 15028 #include 15029 long ftell(FILE *stream); | 15030 CX off_t ftello(FILE *stream); | 15031 15032 DESCRIPTION 15033 CX The functionality described on this reference page is aligned with the ISO C standard. Any 15034 conflict between the requirements described here and the ISO C standard is unintentional. This 15035 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 15036 The ftell( ) function shall obtain the current value of the file-position indicator for the stream 15037 pointed to by stream. 15038 CX The ftello( ) function is identical to ftell( ) except that the return value is of type off_t. 15039 RETURN VALUE 15040 CX Upon successful completion, ftell( ) and ftello( ) shall return the current value of the file-position 15041 indicator for the stream measured in bytes from the beginning of the file. 15042 CX Otherwise, ftell( ) and ftello( ) shall return -1, cast to long and off_t respectively, and set errno to 15043 indicate the error. 15044 ERRORS 15045 CX The ftell( ) and ftello( )functions shall fail if: 15046 CX [EBADF] The file descriptor underlying stream is not an open file descriptor. | 15047 CX [EOVERFLOW] For ftell( ), the current file offset cannot be represented correctly in an object of | 15048 type long. 15049 CX [EOVERFLOW] For ftello( ), the current file offset cannot be represented correctly in an object | 15050 of type off_t. 15051 CX [ESPIPE] The file descriptor underlying stream is associated with a pipe or FIFO. | 15052 The ftell( ) function may fail if: 15053 CX [ESPIPE] The file descriptor underlying stream is associated with a socket. 15054 EXAMPLES 15055 None. 15056 APPLICATION USAGE 15057 None. 15058 RATIONALE 15059 None. 15060 FUTURE DIRECTIONS 15061 None. 15062 SEE ALSO 15063 fgetpos( ), fopen( ), fseek( ), lseek( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 952 Technical Standard (2000) (Draft July 31, 2000) System Interfaces ftell( ) 15064 CHANGE HISTORY 15065 First released in Issue 1. Derived from Issue 1 of the SVID. | 15066 Issue 4 15067 The following change is incorporated for alignment with the ISO C standard: 15068 * The function return value is now defined in full as long. It was previously defined as long. | 15069 Issue 5 15070 Large File Summit extensions are added. 15071 Issue 6 15072 Extensions beyond the ISO C standard are now marked. 15073 The following new requirements on POSIX implementations derive from alignment with the 15074 Single UNIX Specification: 15075 * The ftello ( ) function is added. 15076 * The [EOVERFLOW] error conditions are added. 15077 An additional [ESPIPE] error condition is added for sockets. System Interfaces, Issue 6 953 ftime( ) System Interfaces 15078 NAME 15079 ftime - get date and time (LEGACY) 15080 SYNOPSIS 15081 XSI #include 15082 int ftime(struct timeb *tp); 15083 15084 DESCRIPTION 15085 The ftime( ) function shall set the time and millitm members of the timeb structure pointed to by 15086 tp to contain the seconds and milliseconds portions, respectively, of the current time in seconds 15087 since the Epoch. The contents of the timezone and dstflag members of tp after a call to ftime( ) are 15088 unspecified. 15089 The system clock need not have millisecond granularity. Depending on any granularity 15090 (particularly a granularity of one) renders code non-portable. 15091 RETURN VALUE 15092 Upon successful completion, the ftime( ) function shall return 0; otherwise, -1 shall be returned. 15093 ERRORS 15094 No errors are defined. 15095 EXAMPLES 15096 Getting the Current Time and Date 15097 The following example shows how to get the current system time values using the ftime( ) 15098 function. The timeb structure pointed to by tp is filled with the current system time values for 15099 time and millitm. 15100 #include 15101 struct timeb tp; 15102 int status; 15103 ... 15104 status = ftime(&tp); 15105 APPLICATION USAGE 15106 For applications portability, the time( ) function should be used to determine the current time 15107 instead of ftime( ). 15108 RATIONALE 15109 None. 15110 FUTURE DIRECTIONS 15111 This function may be withdrawn in a future version. 15112 SEE ALSO 15113 ctime( ), gettimeofday( ), time( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 15114 15115 CHANGE HISTORY 15116 First released in Issue 4, Version 2. 15117 Issue 5 15118 Moved from X/OPEN UNIX extension to BASE. 15119 Normative text previously in the APPLICATION USAGE section is moved to the 15120 DESCRIPTION. 954 Technical Standard (2000) (Draft July 31, 2000) System Interfaces ftime( ) 15121 Issue 6 15122 This function is marked LEGACY. 15123 The DESCRIPTION is updated to refer to ``seconds since the Epoch'' rather than ``seconds since 15124 00:00:00 UTC (Coordinated Universal Time), January 1 1970'' for consistency with other time | 15125 functions. System Interfaces, Issue 6 955 ftok( ) System Interfaces 15126 NAME 15127 ftok - generate an IPC key 15128 SYNOPSIS 15129 XSI #include 15130 key_t ftok(const char *path, int id); 15131 15132 DESCRIPTION 15133 The ftok( ) function shall return a key based on path and id that is usable in subsequent calls to 15134 msgget( ), semget( ), and shmget( ). The application shall ensure that the path argument is the path 15135 name of an existing file that the process is able to stat( ). 15136 The ftok( ) function shall return the same key value for all paths that name the same file, when 15137 called with the same id value, and return different key values when called with different id 15138 values or with paths that name different files existing on the same file system at the same time. It 15139 is unspecified whether ftok( ) shall return the same key value when called again after the file 15140 named by path is removed and recreated with the same name. 15141 Only the low order 8-bits of id are significant. The behavior of ftok( ) is unspecified if these bits 15142 are 0. 15143 RETURN VALUE 15144 Upon successful completion, ftok( ) shall return a key. Otherwise, ftok( ) shall return (key_t)-1 15145 and set errno to indicate the error. 15146 ERRORS 15147 The ftok( ) function shall fail if: 15148 [EACCES] Search permission is denied for a component of the path prefix. | 15149 [ELOOP] A loop exists in symbolic links encountered during resolution of the path | 15150 argument. | 15151 [ENAMETOOLONG] | 15152 The length of the path argument exceeds {PATH_MAX} or a path name 15153 component is longer than {NAME_MAX}. 15154 [ENOENT] A component of path does not name an existing file or path is an empty string. | 15155 [ENOTDIR] A component of the path prefix is not a directory. | 15156 The ftok( ) function may fail if: 15157 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during | 15158 resolution of the path argument. | 15159 [ENAMETOOLONG] | 15160 Path name resolution of a symbolic link produced an intermediate result 15161 whose length exceeds {PATH_MAX}. 956 Technical Standard (2000) (Draft July 31, 2000) System Interfaces ftok( ) 15162 EXAMPLES 15163 Getting an IPC Key 15164 The following example gets a unique key that can be used by the IPC functions semget( ), 15165 msgget( ), and shmget( ). The key returned by ftok( ) for this example is based on the ID value S 15166 and the path name /tmp. 15167 #include 15168 ... 15169 key_t key; 15170 char *path = "/tmp"; 15171 int id = 'S'; 15172 key = ftok(path, id); 15173 Saving an IPC Key 15174 The following example gets a unique key based on the path name /tmp and the ID value a. It 15175 also assigns the value of the resulting key to the semkey variable so that it will be available to a 15176 later call to semget( ), msgget( ), or shmget( ). 15177 #include 15178 ... 15179 key_t semkey; 15180 if ((semkey = ftok("/tmp", 'a')) == (key_t) -1) { 15181 perror("IPC error: ftok"); exit(1); 15182 } 15183 APPLICATION USAGE 15184 For maximum portability, id should be a single-byte character. 15185 RATIONALE 15186 None. 15187 FUTURE DIRECTIONS 15188 None. 15189 SEE ALSO 15190 msgget( ), semget( ), shmget( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 15191 CHANGE HISTORY 15192 First released in Issue 4, Version 2. 15193 Issue 5 15194 Moved from X/OPEN UNIX extension to BASE. 15195 Issue 6 15196 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. | 15197 The wording of the mandatory [ELOOP] error condition is updated, and a second optional | 15198 [ELOOP] error condition is added. | System Interfaces, Issue 6 957 ftruncate( ) System Interfaces 15199 NAME 15200 ftruncate - truncate a file to a specified length 15201 SYNOPSIS 15202 #include 15203 int ftruncate(int fildes, off_t length); | 15204 DESCRIPTION | 15205 If fildes is not a valid file descriptor open for writing, the ftruncate( ) function shall fail. 15206 If fildes refers to a regular file, the ftruncate( ) function shall cause the size of the file to be 15207 truncated to length. If the size of the file previously exceeded length, the extra data shall no 15208 longer be available to reads on the file. If the file previously was smaller than this size, 15209 XSI ftruncate( ) shall either increase the size of the file or fail. XSI-conformant systems shall increase | 15210 the size of the file. If the file size is increased, the extended area shall appear as if it were zero- | 15211 filled. The value of the seek pointer shall not be modified by a call to ftruncate( ). | 15212 Upon successful completion, if fildes refers to a regular file, the ftruncate( ) function shall mark 15213 for update the st_ctime and st_mtime fields of the file and the S_ISUID and S_ISGID bits of the file 15214 mode may be cleared. If the ftruncate( ) function is unsuccessful, the file is unaffected. 15215 XSI If the request would cause the file size to exceed the soft file size limit for the process, the 15216 request shall fail and the implementation shall generate the SIGXFSZ signal for the process. 15217 If fildes refers to a directory, ftruncate( ) shall fail. 15218 If fildes refers to any other file type, except a shared memory object, the result is unspecified. 15219 SHM If fildes refers to a shared memory object, ftruncate( ) shall set the size of the shared memory | 15220 object to length. | 15221 MF|SHM If the effect of ftruncate( ) is to decrease the size of a shared memory object or memory mapped | 15222 file and whole pages beyond the new end were previously mapped, then the whole pages 15223 beyond the new end shall be discarded. 15224 MPR If the Memory Protection option is supported, references to discarded pages shall result in the 15225 generation of a SIGBUS signal; otherwise, the result of such references is undefined. 15226 MF|SHM If the effect of ftruncate( ) is to increase the size of a shared memory object, it is unspecified if the | 15227 contents of any mapped pages between the old end-of-file and the new are flushed to the 15228 underlying object. 15229 RETURN VALUE 15230 Upon successful completion, ftruncate( ) shall return 0; otherwise, -1 shall be returned and errno 15231 set to indicate the error. 15232 ERRORS 15233 The ftruncate( ) function shall fail if: 15234 [EINTR] A signal was caught during execution. | 15235 [EINVAL] The length argument was less than 0. | 15236 [EFBIG] or [EINVAL] | 15237 The length argument was greater than the maximum file size. 15238 XSI [EFBIG] The file is a regular file and length is greater than the offset maximum 15239 established in the open file description associated with fildes. 15240 [EIO] An I/O error occurred while reading from or writing to a file system. | 958 Technical Standard (2000) (Draft July 31, 2000) System Interfaces ftruncate( ) 15241 [EBADF] or [EINVAL] | 15242 The fildes argument is not a file descriptor open for writing. 15243 [EINVAL] The fildes argument references a file that was opened without write | 15244 permission. 15245 [EROFS] The named file resides on a read-only file system. | 15246 EXAMPLES 15247 None. 15248 APPLICATION USAGE 15249 None. 15250 RATIONALE 15251 The ftruncate( ) function is part of IEEE Std. 1003.1-200x as it was deemed to be more useful than | 15252 truncate( ). The truncate( ) function is provided as an XSI extension. 15253 FUTURE DIRECTIONS 15254 None. 15255 SEE ALSO 15256 open( ), truncate( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 15257 CHANGE HISTORY 15258 First released in Issue 4, Version 2. 15259 Issue 5 15260 Moved from X/OPEN UNIX extension to BASE and aligned with ftruncate( ) in the POSIX 15261 Realtime Extension. Specifically, the DESCRIPTION is extensively reworded and [EROFS] is 15262 added to the list of mandatory errors that can be returned by ftruncate( ). 15263 Large File Summit extensions are added. 15264 Issue 6 15265 The truncate( ) function has been split out into a separate reference page. 15266 The following new requirements on POSIX implementations derive from alignment with the | 15267 Single UNIX Specification: 15268 * The DESCRIPTION is change to indicate that if the file size is changed, and if the file is a 15269 regular file, the S_ISUID and S_ISGID bits in the file mode may be cleared. 15270 The following changes were made to align with the IEEE P1003.1a draft standard: 15271 * The DESCRIPTION text is updated. 15272 XSI-conformant systems are required to increase the size of the file if the file was previously | 15273 smaller than the size requested. | System Interfaces, Issue 6 959 ftrylockfile( ) System Interfaces 15274 NAME 15275 ftrylockfile - stdio locking functions 15276 SYNOPSIS 15277 TSF #include 15278 int ftrylockfile(FILE *file); 15279 15280 DESCRIPTION 15281 Refer to flockfile ( ). 960 Technical Standard (2000) (Draft July 31, 2000) System Interfaces ftw( ) 15282 NAME 15283 ftw - traverse (walk) a file tree 15284 SYNOPSIS 15285 XSI #include 15286 int ftw(const char *path, int (*fn)(const char *, 15287 const struct stat *ptr, int flag), int ndirs); 15288 15289 DESCRIPTION 15290 The ftw( ) function recursively descends the directory hierarchy rooted in path. For each object in 15291 the hierarchy, ftw( ) shall call the function pointed to by fn, passing it a pointer to a null- 15292 terminated character string containing the name of the object, a pointer to a stat structure 15293 containing information about the object, and an integer. Possible values of the integer, defined 15294 in the header, are: 15295 FTW_D For a directory. 15296 FTW_DNR For a directory that cannot be read. 15297 FTW_F For a file. 15298 FTW_SL For a symbolic link (but see also FTW_NS below). 15299 FTW_NS For an object other than a symbolic link on which stat( ) could not successfully be 15300 executed. If the object is a symbolic link and stat( ) failed, it is unspecified whether 15301 ftw( ) passes FTW_SL or FTW_NS to the user-supplied function. 15302 If the integer is FTW_DNR, descendants of that directory shall not be processed. If the integer is 15303 FTW_NS, the stat structure contains undefined values. An example of an object that would 15304 cause FTW_NS to be passed to the function pointed to by fn would be a file in a directory with 15305 read but without execute (search) permission. 15306 The ftw( ) function shall visit a directory before visiting any of its descendants. 15307 The ftw( ) function shall use at most one file descriptor for each level in the tree. 15308 The argument ndirs should be in the range of 1 to {OPEN_MAX}. 15309 The tree traversal shall continue until the tree is exhausted, an invocation of fn returns a non- 15310 zero value, or some error, other than [EACCES], is detected within ftw( ). 15311 The ndirs argument shall specify the maximum number of directory streams or file descriptors 15312 or both available for use by ftw( ) while traversing the tree. When ftw( ) returns it shall close any 15313 directory streams and file descriptors it uses not counting any opened by the application- 15314 supplied fn function. 15315 RETURN VALUE 15316 If the tree is exhausted, ftw( ) shall return 0. If the function pointed to by fn returns a non-zero 15317 value, ftw( ) shall stop its tree traversal and return whatever value was returned by the function 15318 pointed to by fn. If ftw( ) detects an error, it shall return -1 and set errno to indicate the error. 15319 If ftw( ) encounters an error other than [EACCES] (see FTW_DNR and FTW_NS above), it shall 15320 return -1 and set errno to indicate the error. The external variable errno may contain any error 15321 value that is possible when a directory is opened or when one of the stat functions is executed on 15322 a directory or file. System Interfaces, Issue 6 961 ftw( ) System Interfaces 15323 ERRORS 15324 The ftw( ) function shall fail if: 15325 [EACCES] Search permission is denied for any component of path or read permission is | 15326 denied for path. 15327 [ELOOP] A loop exists in symbolic links encountered during resolution of the path | 15328 argument. | 15329 [ENAMETOOLONG] | 15330 The length of the path argument exceeds {PATH_MAX} or a path name | 15331 component is longer than {NAME_MAX}. | 15332 [ENOENT] A component of path does not name an existing file or path is an empty string. | 15333 [ENOTDIR] A component of path is not a directory. | 15334 The ftw( ) function may fail if: 15335 [EINVAL] The value of the ndirs argument is invalid. | 15336 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during | 15337 resolution of the path argument. | 15338 [ENAMETOOLONG] | 15339 Path name resolution of a symbolic link produced an intermediate result 15340 whose length exceeds {PATH_MAX}. 15341 In addition, if the function pointed to by fn encounters system errors, errno may be set 15342 accordingly. 15343 EXAMPLES 15344 Walking a Directory Structure 15345 The following example walks the current directory structure, calling the fn function for every | 15346 directory entry, using at most 10 file descriptors: | 15347 #include 15348 ... 15349 if (ftw(".", fn, 10) != 0) { 15350 perror("ftw"); exit(2); 15351 } 15352 APPLICATION USAGE 15353 The ftw( ) function may allocate dynamic storage during its operation. If ftw( ) is forcibly 15354 terminated, such as by longjmp( ) or siglongjmp( ) being executed by the function pointed to by fn 15355 or an interrupt routine, ftw( ) does not have a chance to free that storage, so it remains 15356 permanently allocated. A safe way to handle interrupts is to store the fact that an interrupt has 15357 occurred, and arrange to have the function pointed to by fn return a non-zero value at its next 15358 invocation. 15359 RATIONALE 15360 None. 15361 FUTURE DIRECTIONS 15362 None. 962 Technical Standard (2000) (Draft July 31, 2000) System Interfaces ftw( ) 15363 SEE ALSO 15364 longjmp( ), lstat( ), malloc( ), nftw( ), opendir( ), siglongjmp( ), stat( ), the Base Definitions volume of | 15365 IEEE Std. 1003.1-200x, , | 15366 CHANGE HISTORY 15367 First released in Issue 1. Derived from Issue 1 of the SVID. | 15368 Issue 4 15369 The type of argument path is changed from char* to const char*. The argument list for fn has 15370 also been defined. 15371 In the DESCRIPTION, the words ``other than [EACCES]'' are added to the paragraph describing 15372 termination conditions for tree traversal. 15373 The following change is incorporated for alignment with the FIPS requirements: 15374 * In the ERRORS section, the condition whereby [ENAMETOOLONG] is returned if a path 15375 name component is larger that {NAME_MAX} is now defined as mandatory and marked as 15376 an extension. 15377 Issue 4, Version 2 15378 The following changes are incorporated for X/OPEN UNIX conformance: 15379 * The DESCRIPTION is updated to describe the use of the FTW_SL and FTW_NS values for a 15380 symbolic link. 15381 * The DESCRIPTION states that ftw( ) uses at most one file descriptor for each level in the tree. 15382 * The DESCRIPTION constrains ndirs to the range from 1 to {OPEN_MAX}. 15383 * The RETURN VALUE section is updated to describe the case where ftw( ) encounters an error 15384 other than [EACCES]. 15385 * In the ERRORS section, a second [ENAMETOOLONG] condition is defined that may report 15386 excessive length of an intermediate result of path name resolution of a symbolic link. 15387 Issue 5 15388 UX codings in the DESCRIPTION, RETURN VALUE, and ERRORS sections have been changed 15389 to EX. 15390 Issue 6 15391 The following changes are made for alignment with the ISO POSIX-1: 1996 standard: 15392 * The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. 15393 This is since behavior may vary from one file system to another. 15394 The wording of the mandatory [ELOOP] error condition is updated, and a second optional | 15395 [ELOOP] error condition is added. | System Interfaces, Issue 6 963 funlockfile( ) System Interfaces 15396 NAME 15397 funlockfile - stdio locking functions 15398 SYNOPSIS 15399 TSF #include 15400 void funlockfile(FILE *file); 15401 15402 DESCRIPTION 15403 Refer to flockfile ( ). 964 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fwide( ) 15404 NAME 15405 fwide - set stream orientation 15406 SYNOPSIS 15407 #include 15408 #include 15409 int fwide(FILE *stream, int mode); 15410 DESCRIPTION 15411 CX The functionality described on this reference page is aligned with the ISO C standard. Any 15412 conflict between the requirements described here and the ISO C standard is unintentional. This 15413 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 15414 The fwide( ) function shall determine the orientation of the stream pointed to by stream. If mode is 15415 greater than zero, the function first attempts to make the stream wide-oriented. If mode is less 15416 than zero, the function first attempts to make the stream byte-oriented. Otherwise, mode is zero 15417 and the function does not alter the orientation of the stream. 15418 If the orientation of the stream has already been determined, fwide( ) shall not change it. 15419 Because no return value is reserved to indicate an error, an application wishing to check for error 15420 situations should set errno to 0, then call fwide( ), then check errno, and if it is non-zero, assume 15421 an error has occurred. 15422 RETURN VALUE 15423 The fwide( ) function shall return a value greater than zero if, after the call, the stream has wide- 15424 orientation, a value less than zero if the stream has byte-orientation, or zero if the stream has no 15425 orientation. 15426 ERRORS 15427 The fwide( ) function may fail if: 15428 CX [EBADF] The stream argument is not a valid stream. | 15429 EXAMPLES 15430 None. 15431 APPLICATION USAGE 15432 A call to fwide( ) with mode set to zero can be used to determine the current orientation of a 15433 stream. 15434 RATIONALE 15435 None. 15436 FUTURE DIRECTIONS 15437 None. 15438 SEE ALSO 15439 The Base Definitions volume of IEEE Std. 1003.1-200x, | 15440 CHANGE HISTORY 15441 First released in Issue 5. Included for alignment with ISO/IEC 9899: 1990/Amendment 1: 1995 15442 (E). 15443 Issue 6 15444 Extensions beyond the ISO C standard are now marked. System Interfaces, Issue 6 965 fwprintf( ) System Interfaces 15445 NAME 15446 fwprintf, swprintf, wprintf - print formatted wide-character output 15447 SYNOPSIS 15448 #include 15449 #include 15450 int fwprintf(FILE *restrict stream, const wchar_t *restrict format, ...);| 15451 int swprintf(wchar_t *restrict ws, size_t n, const wchar_t *restrict format, ...);| 15452 int wprintf(const wchar_t *restrict format, ...); | 15453 DESCRIPTION | 15454 CX The functionality described on this reference page is aligned with the ISO C standard. Any 15455 conflict between the requirements described here and the ISO C standard is unintentional. This 15456 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 15457 The fwprintf( ) function places output on the named output stream. The wprintf( ) function places 15458 output on the standard output stream stdout. The swprintf( ) function places output followed by 15459 the null wide character in consecutive wide characters starting at *ws; no more than n wide | 15460 characters are written, including a terminating null wide character, which is always added 15461 (unless n is zero). 15462 Each of these functions converts, formats, and prints its arguments under control of the format 15463 wide-character string. The format is composed of zero or more directives: ordinary wide- 15464 characters, which are simply copied to the output stream, and conversion specifications, each of 15465 which results in the fetching of zero or more arguments. The results are undefined if there are 15466 insufficient arguments for the format. If the format is exhausted while arguments remain, the 15467 excess arguments are evaluated but are otherwise ignored. 15468 XSI Conversions can be applied to the nth argument after the format in the argument list, rather than 15469 to the next unused argument. In this case, the conversion wide character '%' (see below) is 15470 replaced by the sequence "%n$", where n is a decimal integer in the range [1,{NL_ARGMAX}], 15471 giving the position of the argument in the argument list. This feature provides for the definition 15472 of format wide-character strings that select arguments in an order appropriate to specific 15473 languages (see the EXAMPLES section). 15474 In format wide-character strings containing the "%n$" form of conversion specifications, 15475 numbered arguments in the argument list can be referenced from the format wide-character 15476 string as many times as required. 15477 In format wide-character strings containing the '%' form of conversion specifications, each 15478 argument in the argument list is used exactly once. 15479 All forms of the fwprintf( ) function allow for the insertion of a locale-dependent radix character | 15480 in the output string, output as a wide-character value. The radix character is defined in the 15481 program's locale (category LC_NUMERIC). In the POSIX locale, or in a locale where the radix 15482 character is not defined, the radix character defaults to a period ('.'). 15483 XSI Each conversion specification is introduced by the '%' wide character or by the wide-character 15484 sequence "%n$",after which the following appear in sequence: 15485 * Zero or more flags (in any order), which modify the meaning of the conversion specification. 15486 * An optional minimum field width. If the converted value has fewer wide characters than the 15487 field width, it shall be padded with spaces by default on the left; it shall be padded on the 15488 right, if the left-adjustment flag ('-'), described below, is given to the field width. The field 15489 width takes the form of an asterisk ('*'), described below, or a decimal integer. 966 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fwprintf( ) 15490 * An optional precision that gives the minimum number of digits to appear for the d, i, o, u, x, 15491 and X conversions; the number of digits to appear after the radix character for the e, E, and f 15492 conversions; the maximum number of significant digits for the g and G conversions; or the 15493 maximum number of wide characters to be printed from a string in s conversions. The 15494 precision takes the form of a period ('.') followed either by an asterisk ('*'), described 15495 below, or an optional decimal digit string, where a null digit string is treated as 0. If a 15496 precision appears with any other conversion wide character, the behavior is undefined. 15497 * An optional length modifier that specifies the size of the argument. | 15498 * A conversion wide character that indicates the type of conversion to be applied. 15499 A field width, or precision, or both, may be indicated by an asterisk ('*'). In this case an 15500 argument of type int supplies the field width or precision. The application shall ensure that 15501 arguments specifying field width, or precision, or both appear in that order before the argument, 15502 if any, to be converted. A negative field width is taken as a '-' flag followed by a positive field 15503 XSI width. A negative precision is taken as if the precision were omitted. In format wide-character 15504 strings containing the "%n$" form of a conversion specification, a field width or precision may 15505 be indicated by the sequence "*m$", where m is a decimal integer in the range 15506 [1,{NL_ARGMAX}] giving the position in the argument list (after the format argument) of an 15507 integer argument containing the field width or precision, for example: 15508 wprintf(L"%1$d:%2$.*3$d:%4$.*3$d\n", hour, min, precision, sec); 15509 The format can contain either numbered argument specifications (that is, "%n$" and "*m$"), or 15510 unnumbered argument specifications (that is, '%' and '*'), but normally not both. The only 15511 exception to this is that "%%" can be mixed with the "%n$" form. The results of mixing 15512 numbered and unnumbered argument specifications in a format wide-character string are 15513 undefined. When numbered argument specifications are used, specifying the Nth argument 15514 requires that all the leading arguments, from the first to the (N-1)th, are specified in the format 15515 wide-character string. 15516 The flag wide characters and their meanings are: 15517 XSI ' The integer portion of the result of a decimal conversion (%i, %d, %u, %f, %g, or %G) 15518 shall be formatted with thousands' grouping wide characters. For other conversions, 15519 the behavior is undefined. The numeric grouping wide character is used. | 15520 - The result of the conversion shall be left-justified within the field. The conversion shall 15521 be right-justified if this flag is not specified. 15522 + The result of a signed conversion shall always begin with a sign ('+' or '-'). The 15523 conversion shall begin with a sign only when a negative value is converted if this flag is 15524 not specified. 15525 If the first wide character of a signed conversion is not a sign, or if a signed conversion 15526 results in no wide characters, a space shall be prefixed to the result. This means that if 15527 the and '+' flags both appear, the space flag shall be ignored. 15528 # This flag specifies that the value is to be converted to an alternative form. For o 15529 conversion, it increases the precision (if necessary) to force the first digit of the result to 15530 be 0. For x or X conversions, a non-zero result ahsll have 0x (or 0X) prefixed to it. For e, 15531 E, f, g, or G conversions, the result shall always contain a radix character, even if no 15532 digits follow it. Without this flag, a radix character appears in the result of these 15533 conversions only if a digit follows it. For g and G conversions, trailing zeros shall not be 15534 removed from the result as they normally are. For other conversions, the behavior is 15535 undefined. System Interfaces, Issue 6 967 fwprintf( ) System Interfaces 15536 0 For d, i, o, u, x, X, e, E, f, g, and G conversions, leading zeros (following any indication of 15537 sign or base) are used to pad to the field width; no space padding is performed. If the 0 15538 and '-' flags both appear, the 0 flag shall be ignored. For d, i, o, u, x, and X 15539 conversions, if a precision is specified, the 0 flag shall be ignored. If the 0 and ''' flags 15540 both appear, the grouping wide characters are inserted before zero padding. For other 15541 conversions, the behavior is undefined. 15542 The length modifiers and their meanings are: | 15543 hh Specifies that a following d, i, o, u, x, or X conversion specifier applies to a signed char | 15544 or unsigned char argument (the argument will have been promoted according to the | 15545 integer promotions, but its value shall be converted to signed char or unsigned char | 15546 before printing); or that a following n conversion specifier applies to a pointer to a | 15547 signed char argument. | 15548 h Specifies that a following d, i, o, u, x, or X conversion specifier applies to a short or | 15549 unsigned short argument (the argument will have been promoted according to the | 15550 integer promotions, but its value shall be converted to short or unsigned short before | 15551 printing); or that a following n conversion specifier applies to a pointer to a short | 15552 argument. | 15553 l (ell) Specifies that a following d, i, o, u, x, or X conversion specifier applies to a long or | 15554 unsigned long argument; that a following n conversion specifier applies to a pointer to | 15555 a long argument; that a following c conversion specifier applies to a wint_t argument; | 15556 that a following s conversion specifier applies to a pointer to a wchar_t argument; or | 15557 has no effect on a following a, A, e, E, f, F, g, or G conversion specifier. | 15558 ll (ell-ell)Specifies that a following d, i, o, u, x, or X conversion specifier applies to a long long or | 15559 unsigned long long argument; or that a following n conversion specifier applies to a | 15560 pointer to a long long argument. | 15561 j Specifies that a following d, i, o, u, x, or X conversion specifier applies to an intmax_t or | 15562 uintmax_t argument; or that a following n conversion specifier applies to a pointer to | 15563 an intmax_t argument. | 15564 z Specifies that a following d, i, o, u, x, or X conversion specifier applies to a size_t or the | 15565 corresponding signed integer type argument; or that a following n conversion specifier | 15566 applies to a pointer to a signed integer type corresponding to size_t argument. | 15567 t Specifies that a following d, i, o, u, x, or X conversion specifier applies to a ptrdiff_t or | 15568 the corresponding unsigned type argument; or that a following n conversion specifier | 15569 applies to a pointer to a ptrdiff_t argument. | 15570 L Specifies that a following a, A, e, E, f, F, g, or G conversion specifier applies to a long | 15571 double argument. | 15572 If a length modifier appears with any conversion specifier other than as specified above, the | 15573 behavior is undefined. | 15574 The conversion wide characters and their meanings are: | 15575 d, i The int argument is converted to a signed decimal in the style [-]dddd. The precision 15576 specifies the minimum number of digits to appear; if the value being converted can be 15577 represented in fewer digits, it shall be expanded with leading zeros. The default 15578 precision is 1. The result of converting 0 with an explicit precision of 0 is no wide 15579 characters. 15580 o The unsigned argument is converted to unsigned octal format in the style dddd. The | 15581 precision specifies the minimum number of digits to appear; if the value being 968 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fwprintf( ) 15582 converted can be represented in fewer digits, it shall be expanded with leading zeros. 15583 The default precision is 1. The result of converting 0 with an explicit precision of 0 is no 15584 wide characters. 15585 u The unsigned argument is converted to unsigned decimal format in the style dddd. The | 15586 precision specifies the minimum number of digits to appear; if the value being 15587 converted can be represented in fewer digits, it shall be expanded with leading zeros. 15588 The default precision is 1. The result of converting 0 with an explicit precision of 0 is no 15589 wide characters. 15590 x The unsigned argument is converted to unsigned hexadecimal format in the style dddd; | 15591 the letters "abcdef" are used. The precision specifies the minimum number of digits 15592 to appear; if the value being converted can be represented in fewer digits, it shall be 15593 expanded with leading zeros. The default precision is 1. The result of converting 0 with 15594 an explicit precision of 0 is no wide characters. 15595 X Behaves the same as the x conversion wide character except that letters "ABCDEF" are 15596 used instead of "abcdef". | 15597 f, F The double argument is converted to decimal notation in the style [-]ddd.ddd, where | 15598 the number of digits after the radix character is equal to the precision specification. If 15599 the precision is missing, it is taken as 6; if the precision is explicitly 0 and no '#' flag is 15600 present, no radix character appears. If a radix character appears, at least one digit 15601 appears before it. The value is rounded to the appropriate number of digits. 15602 A double argument representing an infinity is converted in one of the styles [-]inf or | 15603 [-]infinity; which style is implementation-defined. A double argument representing a | 15604 NaN is converted in one of the styles [-]nan or [-]nan(n-char-sequence); which style, and | 15605 the meaning of any n-char-sequence, is implementation-defined. The F conversion | 15606 specifier produces INF, INFINITY, or NAN instead of inf, infinity, or nan, respectively. | 15607 e, E The double argument is converted in the style [-]d.ddde±dd, where there is one digit | 15608 before the radix character (which is non-zero if the argument is non-zero) and the 15609 number of digits after it is equal to the precision; if the precision is missing, it is taken 15610 as 6; if the precision is 0 and no '#' flag is present, no radix character appears. The 15611 value is rounded to the appropriate number of digits. The E conversion wide character 15612 shall produce a number with E instead of e introducing the exponent. The exponent 15613 always contains at least two digits. If the value is 0, the exponent is 0. 15614 A double argument representing an infinity or NaN is converted in the style of an f or F | 15615 conversion specifier. | 15616 g, G The double argument is converted in the style f or e (or in the style E in the case of a G | 15617 conversion wide character), with the precision specifying the number of significant 15618 digits. If an explicit precision is 0, it is taken as 1. The style used depends on the value 15619 converted; style e (or E) shall be used only if the exponent resulting from such a 15620 conversion is less than -4 or greater than or equal to the precision. Trailing zeros are 15621 removed from the fractional portion of the result; a radix character appears only if it is 15622 followed by a digit. 15623 A double argument representing an infinity or NaN is converted in the style of an f or F | 15624 conversion specifier. | 15625 a, A A double argument representing a floating-point number is converted in the style | 15626 [-]0xh.hhhh p1d, where there is one hexadecimal digit (which is non-zero if the | 15627 argument is a normalized floating-point number and is otherwise unspecified) before | 15628 the decimal-point character 235) and the number of hexadecimal digits after it is equal | System Interfaces, Issue 6 969 fwprintf( ) System Interfaces 15629 to the precision; if the precision is missing and FLT_RADIX is a power of 2, then the | 15630 precision is sufficient for an exact representation of the value; if the precision is missing | 15631 and FLT_RADIX is not a power of 2, then the precision is sufficient to distinguish 236) | 15632 values of type double, except that trailing zeros may be omitted; if the precision is zero | 15633 and the '#' flag is not specified, no decimal-point character appears. The letters | 15634 "abcdef" are used for a conversion and the letters "ABCDEF" for A conversion. The A | 15635 conversion specifier produces a number with 'X' and 'P' instead of 'x' and 'p'. | 15636 The exponent always contains at least one digit, and only as many more digits as | 15637 necessary to represent the decimal exponent of 2. If the value is zero, the exponent is | 15638 zero. | 15639 A double argument representing an infinity or NaN is converted in the style of an f or F | 15640 conversion specifier. | 15641 c If no l (ell) qualifier is present, the int argument is converted to a wide character as if by 15642 calling the btowc( ) function and the resulting wide character is written. Otherwise, the 15643 wint_t argument is converted to wchar_t, and written. 15644 s If no l (ell) qualifier is present, the application shall ensure that the argument is a 15645 pointer to a character array containing a character sequence beginning in the initial 15646 shift state. Characters from the array are converted as if by repeated calls to the 15647 mbrtowc( ) function, with the conversion state described by an mbstate_t object 15648 initialized to zero before the first character is converted, and written up to (but not 15649 including) the terminating null wide character. If the precision is specified, no more 15650 than that many wide characters are written. If the precision is not specified, or is 15651 greater than the size of the array, the application shall ensure that the array contains a 15652 null wide character. 15653 If an l (ell) qualifier is present, the application shall ensure that the argument is a 15654 pointer to an array of type wchar_t. Wide characters from the array are written up to 15655 (but not including) a terminating null wide character. If no precision is specified, or is 15656 greater than the size of the array, the application shall ensure that the array contains a 15657 null wide character. If a precision is specified, no more than that many wide characters 15658 are written. 15659 p The application shall ensure that the argument is a pointer to void. The value of the 15660 pointer is converted to a sequence of printable wide characters, in an implementation- | 15661 defined manner. | 15662 n The application shall ensure that the argument is a pointer to an integer into which is 15663 written the number of wide characters written to the output so far by this call to one of 15664 the fwprintf( ) functions. No argument is converted, but one is consumed. If the | 15665 conversion specification includes any flags, a field width, or a precision, the behavior is | 15666 undefined. | 15667 XSI C Same as lc. 15668 XSI S Same as ls. 15669 % Output a '%' wide character; no argument is converted. The entire conversion 15670 specification shall be "%%". 15671 If a conversion specification does not match one of the above forms, the behavior is undefined. 15672 In no case does a nonexistent or small field width cause truncation of a field; if the result of a 15673 conversion is wider than the field width, the field is simply expanded to contain the conversion 15674 result. Characters generated by fwprintf( ) and wprintf( ) are printed as if fputwc( ) had been 15675 called. 970 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fwprintf( ) 15676 For a and A conversions, if FLT_RADIX is a power of 2, the value is correctly rounded to a | 15677 hexadecimal floating number with the given precision. | 15678 If FLT_RADIX is not a power of 2, the result should be one of the two adjacent numbers in | 15679 hexadecimal floating style with the given precision, with the extra stipulation that the error | 15680 should have a correct sign for the current rounding direction. | 15681 For e, E, f, F, g, and G conversions, if the number of significant decimal digits is at most | 15682 DECIMAL_DIG, then the result should be correctly rounded. If the number of significant | 15683 decimal digits is more than DECIMAL_DIG but the source value is exactly representable with | 15684 DECIMAL_DIG digits, then the result should be an exact representation with trailing zeros. | 15685 Otherwise, the source value is bounded by two adjacent decimal strings "L < U", both having | 15686 DECIMAL_DIG significant digits; the value of the resultant decimal string "D" should satisfy "L | 15687 <= D <= U", with the extra stipulation that the error should have a correct sign for the current | 15688 rounding direction. | 15689 CX The st_ctime and st_mtime fields of the file shall be marked for update between the call to a | 15690 successful execution of fwprintf( ) or wprintf( ) and the next successful completion of a call to 15691 fflush( ) or fclose( ) on the same stream, or a call to exit( ) or abort( ). 15692 RETURN VALUE 15693 Upon successful completion, these functions shall return the number of wide characters 15694 transmitted, excluding the terminating null wide character in the case of swprintf( ), or a negative 15695 CX value if an output error was encountered, and set errno to indicate the error. 15696 If n or more wide characters were requested to be written, swprintf( ) shall return a negative 15697 CX value, and set errno to indicate the error. 15698 ERRORS 15699 For the conditions under which fwprintf( ) and wprintf( ) fail and may fail, refer to fputwc( ). 15700 In addition, all forms of fwprintf( ) may fail if: 15701 XSI [EILSEQ] A wide-character code that does not correspond to a valid character has been | 15702 detected. 15703 XSI [EINVAL] There are insufficient arguments. | 15704 In addition, wprintf( ) and fwprintf( ) may fail if: 15705 XSI [ENOMEM] Insufficient storage space is available. | 15706 EXAMPLES 15707 To print the language-independent date and time format, the following statement could be used: 15708 wprintf(format, weekday, month, day, hour, min); 15709 For American usage, format could be a pointer to the wide-character string: 15710 L"%s, %s %d, %d:%.2d\n" 15711 producing the message: 15712 Sunday, July 3, 10:02 15713 whereas for German usage, format could be a pointer to the wide-character string: 15714 L"%1$s, %3$d. %2$s, %4$d:%5$.2d\n" 15715 producing the message: 15716 Sonntag, 3. Juli, 10:02 System Interfaces, Issue 6 971 fwprintf( ) System Interfaces 15717 APPLICATION USAGE 15718 None. 15719 RATIONALE 15720 None. 15721 FUTURE DIRECTIONS 15722 None. 15723 SEE ALSO 15724 btowc( ), fputwc( ), fwscanf( ), mbrtowc( ), setlocale( ), the Base Definitions volume of | 15725 IEEE Std. 1003.1-200x, , , the Base Definitions volume of | 15726 IEEE Std. 1003.1-200x, Chapter 7, Locale | 15727 CHANGE HISTORY 15728 First released in Issue 5. Included for alignment with ISO/IEC 9899: 1990/Amendment 1: 1995 15729 (E). 15730 Issue 6 15731 The Open Group corrigenda item U040/1 has been applied to the RETURN VALUE section, 15732 describing the case if n or more wide characters are requested to be written using swprintf( ). 15733 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. | 15734 The following changes are made for alignment with the ISO/IEC 9899: 1999 standard: | 15735 * The prototypes for fwprintf( ), swprintf( ), and wprintf( ) are updated. || 15736 * The DESCRIPTION is updated. | 972 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fwrite( ) 15737 NAME 15738 fwrite - binary output 15739 SYNOPSIS 15740 #include 15741 size_t fwrite(const void *restrict ptr, size_t size, size_t nitems, | 15742 FILE *restrict stream); | 15743 DESCRIPTION | 15744 CX The functionality described on this reference page is aligned with the ISO C standard. Any 15745 conflict between the requirements described here and the ISO C standard is unintentional. This 15746 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 15747 The fwrite( ) function shall write, from the array pointed to by ptr, up to nitems members whose 15748 size is specified by size, to the stream pointed to by stream. For each object, size calls are made to | 15749 the fputc( ) function, taking the values (in order) from an array of unsigned char exactly | 15750 overlaying the object. The file-position indicator for the stream (if defined) shall be advanced by | 15751 the number of bytes successfully written. If an error occurs, the resulting value of the file- | 15752 position indicator for the stream is indeterminate. | 15753 CX The st_ctime and st_mtime fields of the file shall be marked for update between the successful 15754 execution of fwrite( ) and the next successful completion of a call to fflush( ) or fclose( ) on the 15755 same stream, or a call to exit( ) or abort( ). 15756 RETURN VALUE 15757 The fwrite( ) function shall return the number of members successfully written, which may be 15758 less than nitems if a write error is encountered. If size or nitems is 0, fwrite( ) shall return 0 and the 15759 state of the stream remains unchanged. Otherwise, if a write error occurs, the error indicator for 15760 CX the stream shall be set, and errno shall be set to indicate the error. 15761 ERRORS 15762 Refer to fputc( ). 15763 EXAMPLES 15764 None. 15765 APPLICATION USAGE 15766 Because of possible differences in member length and byte ordering, files written using fwrite( ) 15767 are application-dependent, and possibly cannot be read using fread( ) by a different application 15768 or by the same application on a different processor. 15769 RATIONALE 15770 None. 15771 FUTURE DIRECTIONS 15772 None. 15773 SEE ALSO 15774 ferror( ), fopen( ), printf( ), putc( ), puts( ), write( ), the Base Definitions volume of | 15775 IEEE Std. 1003.1-200x, | 15776 CHANGE HISTORY 15777 First released in Issue 1. Derived from Issue 1 of the SVID. | 15778 Issue 4 15779 In the DESCRIPTION, the text is changed to make it clear that the function advances the file- 15780 position indicator by the number of bytes successfully written rather than the number of 15781 characters, which could include multi-byte sequences. System Interfaces, Issue 6 973 fwrite( ) System Interfaces 15782 The following change is incorporated for alignment with the ISO C standard: 15783 * The type of argument ptr is changed from void* to const void*. 15784 Issue 6 15785 Extensions beyond the ISO C standard are now marked. | 15786 The following changes are made for alignment with the ISO/IEC 9899: 1999 standard: | 15787 * The fwrite( ) prototype is updated. || 15788 * The DESCRIPTION is updated to clarify how the data is written out using fputc( ). | 974 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fwscanf( ) 15789 NAME 15790 fwscanf, swscanf, wscanf - convert formatted wide-character input 15791 SYNOPSIS 15792 #include 15793 #include 15794 int fwscanf(FILE *restrict stream, const wchar_t *restrict format, ... );| 15795 int swscanf(const wchar_t *restrict ws, | 15796 const wchar_t *restrict format, ... ); | 15797 int wscanf(const wchar_t *format, ... ); | 15798 DESCRIPTION 15799 CX The functionality described on this reference page is aligned with the ISO C standard. Any 15800 conflict between the requirements described here and the ISO C standard is unintentional. This 15801 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 15802 The fwscanf( ) function reads from the named input stream. The wscanf( ) function reads from the 15803 standard input stream stdin. The swscanf( ) function reads from the wide-character string ws. | 15804 Each function reads wide characters, interprets them according to a format, and stores the 15805 results in its arguments. Each expects, as arguments, a control wide-character string format 15806 described below, and a set of pointer arguments indicating where the converted input should be 15807 stored. The result is undefined if there are insufficient arguments for the format. If the format is 15808 exhausted while arguments remain, the excess arguments are evaluated but are otherwise 15809 ignored. 15810 XSI Conversions can be applied to the nth argument after the format in the argument list, rather than 15811 to the next unused argument. In this case, the conversion wide character '%' (see below) is 15812 replaced by the sequence "%n$", where n is a decimal integer in the range [1,{NL_ARGMAX}]. 15813 This feature provides for the definition of format wide-character strings that select arguments in 15814 an order appropriate to specific languages. In format wide-character strings containing the 15815 "%n$" form of conversion specifications, it is unspecified whether numbered arguments in the 15816 argument list can be referenced from the format wide-character string more than once. 15817 The format can contain either form of a conversion specification-that is, '%' or "%n$"-but the 15818 two forms cannot normally be mixed within a single format wide-character string. The only 15819 exception to this is that "%%" or "%*" can be mixed with the "%n$" form. 15820 The fwscanf( ) function in all its forms allows for detection of a language-dependent radix 15821 character in the input string, encoded as a wide-character value. The radix character is defined in 15822 the program's locale (category LC_NUMERIC). In the POSIX locale, or in a locale where the 15823 radix character is not defined, the radix character defaults to a period ('.'). 15824 The format is a wide-character string composed of zero or more directives. Each directive is 15825 composed of one of the following: one or more white-space wide characters (, , 15826 , , or characters); an ordinary wide character (neither '%' 15827 nor a white-space character); or a conversion specification. Each conversion specification is 15828 XSI introduced by a '%' or the sequence "%n$"after which the following appear in sequence: 15829 * An optional assignment-suppressing character '*'. 15830 * An optional non-zero decimal integer that specifies the maximum field width. 15831 * An optional length modifier that specifies the size of the receiving object. | 15832 * A conversion wide character that specifies the type of conversion to be applied. The valid 15833 conversion wide characters are described below. System Interfaces, Issue 6 975 fwscanf( ) System Interfaces 15834 The fwscanf( ) functions execute each directive of the format in turn. If a directive fails, as 15835 detailed below, the function shall return. Failures are described as input failures (due to the 15836 unavailability of input bytes) or matching failures (due to inappropriate input). 15837 A directive composed of one or more white-space wide characters is executed by reading input 15838 until no more valid input can be read, or up to the first wide character which is not a white- 15839 space wide character, which remains unread. 15840 A directive that is an ordinary wide character is executed as follows. The next wide character is 15841 read from the input and compared with the wide character that comprises the directive; if the 15842 comparison shows that they are not equivalent, the directive fails, and the differing and | 15843 subsequent wide characters remain unread. Similarly, if end-of-file, an encoding error, or a read | 15844 error prevents a wide character from being read, the directive fails. | 15845 A directive that is a conversion specification defines a set of matching input sequences, as 15846 described below for each conversion wide character. A conversion specification is executed in 15847 the following steps. 15848 Input white-space wide characters (as specified by iswspace( )) are skipped, unless the conversion 15849 specification includes a '[', c, or n conversion character. 15850 An item is read from the input, unless the conversion specification includes an n conversion 15851 wide character. An input item is defined as the longest sequence of input wide characters, not 15852 exceeding any specified field width, which is an initial subsequence of a matching sequence. The 15853 first wide character, if any, after the input item remains unread. If the length of the input item is 15854 0, the execution of the conversion specification fails; this condition is a matching failure, unless 15855 end-of-file, an encoding error, or a read error prevented input from the stream, in which case it is 15856 an input failure. 15857 Except in the case of a '%' conversion wide character, the input item (or, in the case of a %n 15858 conversion specification, the count of input wide characters) is converted to a type appropriate 15859 to the conversion wide character. If the input item is not a matching sequence, the execution of 15860 the conversion specification fails; this condition is a matching failure. Unless assignment 15861 suppression was indicated by a '*', the result of the conversion is placed in the object pointed 15862 to by the first argument following the format argument that has not already received a 15863 XSI conversion result if the conversion specification is introduced by '%', or in the nth argument if 15864 introduced by the wide-character sequence "%n$". If this object does not have an appropriate 15865 type, or if the result of the conversion cannot be represented in the space provided, the behavior 15866 is undefined. 15867 The length modifiers and their meanings are: | 15868 hh Specifies that a following d, i, o, u, x, X, or n conversion specifier applies to an argument | 15869 with type pointer to signed char or unsigned char. | 15870 h Specifies that a following d, i, o, u, x, X, or n conversion specifier applies to an argument | 15871 with type pointer to short or unsigned short. | 15872 l (ell) Specifies that a following d, i, o, u, x, X, or n conversion specifier applies to an argument | 15873 with type pointer to long or unsigned long; that a following a, A, e, E, f, F, g, or G | 15874 conversion specifier applies to an argument with type pointer to double; or that a | 15875 following c, s, or '[' conversion specifier applies to an argument with type pointer to | 15876 wchar_t. | 15877 ll (ell-ell)Specifies that a following d, i, o, u, x, X, or n conversion specifier applies to an argument | 15878 with type pointer to long long or unsigned long long. | 976 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fwscanf( ) 15879 j Specifies that a following d, i, o, u, x, X, or n conversion specifier applies to an argument | 15880 with type pointer to intmax_t or uintmax_t. | 15881 z Specifies that a following d, i, o, u, x, X, or n conversion specifier applies to an argument | 15882 with type pointer to size_t or the corresponding signed integer type. | 15883 t Specifies that a following d, i, o, u, x, X, or n conversion specifier applies to an argument | 15884 with type pointer to ptrdiff_t or the corresponding unsigned type. | 15885 L Specifies that a following a, A, e, E, f, F, g, or G conversion specifier applies to an | 15886 argument with type pointer to long double. | 15887 If a length modifier appears with any conversion specifier other than as specified above, the | 15888 behavior is undefined. | 15889 The following conversion wide characters are valid: | 15890 d Matches an optionally signed decimal integer, whose format is the same as expected for 15891 the subject sequence of wcstol( ) with the value 10 for the base argument. In the absence 15892 of a size modifier, the application shall ensure that the corresponding argument is a 15893 pointer to int. 15894 i Matches an optionally signed integer, whose format is the same as expected for the 15895 subject sequence of wcstol( ) with 0 for the base argument. In the absence of a size 15896 modifier, the application shall ensure that the corresponding argument is a pointer to 15897 int. 15898 o Matches an optionally signed octal integer, whose format is the same as expected for 15899 the subject sequence of wcstoul( ) with the value 8 for the base argument. In the absence 15900 of a size modifier, the application shall ensure that the corresponding argument is a 15901 pointer to unsigned. | 15902 u Matches an optionally signed decimal integer, whose format is the same as expected for 15903 the subject sequence of wcstoul( ) with the value 10 for the base argument. In the absence 15904 of a size modifier, the application shall ensure that the corresponding argument is a 15905 pointer to unsigned. | 15906 x Matches an optionally signed hexadecimal integer, whose format is the same as 15907 expected for the subject sequence of wcstoul( ) with the value 16 for the base argument. 15908 In the absence of a size modifier, the application shall ensure that the corresponding 15909 argument is a pointer to unsigned. | 15910 a, e, f, g Matches an optionally signed floating-point number, infinity, or NaN whose format is | 15911 the same as expected for the subject sequence of wcstod( ). In the absence of a size | 15912 modifier, the application shall ensure that the corresponding argument is a pointer to 15913 float. 15914 If the fwprintf( ) family of functions generates character string representations for | 15915 infinity and NaN (a symbolic entity encoded in floating-point format) to support | 15916 IEEE Std. 754-1985, the fwscanf( ) family of functions shall recognize them as input. | 15917 s Matches a sequence of non white-space wide characters. If no l (ell) qualifier is present, 15918 characters from the input field are converted as if by repeated calls to the wcrtomb( ) 15919 function, with the conversion state described by an mbstate_t object initialized to zero 15920 before the first wide character is converted. The application shall ensure that the 15921 corresponding argument is a pointer to a character array large enough to accept the 15922 sequence and the terminating null character, which shall be added automatically. System Interfaces, Issue 6 977 fwscanf( ) System Interfaces 15923 Otherwise, the application shall ensure that the corresponding argument is a pointer to 15924 an array of wchar_t large enough to accept the sequence and the terminating null wide 15925 character, which shall be added automatically. 15926 [ Matches a non-empty sequence of wide characters from a set of expected wide 15927 characters (the scanset). If no l (ell) qualifier is present, wide characters from the input 15928 field are converted as if by repeated calls to the wcrtomb( ) function, with the conversion 15929 state described by an mbstate_t object initialized to zero before the first wide character 15930 is converted. The application shall ensure that the corresponding argument is a pointer 15931 to a character array large enough to accept the sequence and the terminating null 15932 character, which shall be added automatically. 15933 If an l (ell) qualifier is present, the application shall ensure that the corresponding 15934 argument is a pointer to an array of wchar_t large enough to accept the sequence and 15935 the terminating null wide character, which shall be added automatically. 15936 The conversion specification includes all subsequent wide characters in the format 15937 string up to and including the matching right square bracket (']'). The wide 15938 characters between the square brackets (the scanlist) comprise the scanset, unless the 15939 wide character after the left square bracket is a circumflex (' '), in which case the 15940 scanset contains all wide characters that do not appear in the scanlist between the 15941 circumflex and the right square bracket. If the conversion specification begins with 15942 "[ ]" or "[ ]", the right square bracket is included in the scanlist and the next right 15943 square bracket is the matching right square bracket that ends the conversion 15944 specification; otherwise, the first right square bracket is the one that ends the 15945 conversion specification. If a '-' is in the scanlist and is not the first wide character, 15946 nor the second where the first wide character is a ' ', nor the last wide character, the | 15947 behavior is implementation-defined. | 15948 c Matches a sequence of wide characters of exactly the number specified by the field | 15949 width (1 if no field width is present in the conversion specification). | 15950 If no l (ell) length modifier is present, characters from the input field are converted as if | 15951 by repeated calls to the wcrtomb( ) function, with the conversion state described by an | 15952 mbstate_t object initialized to zero before the first wide character is converted. The | 15953 corresponding argument shall be a pointer to the initial element of a character array | 15954 large enough to accept the sequence. No null character is added. | 15955 If an l (ell) length modifier is present, the corresponding argument shall be a pointer to | 15956 the initial element of an array of wchar_t large enough to accept the sequence. No null | 15957 wide character is added. | 15958 Otherwise, the application shall ensure that the corresponding argument is a pointer to | 15959 an array of wchar_t large enough to accept the sequence. No null wide character is 15960 added. 15961 p Matches an implementation-defined set of sequences, which shall be the same as the set | 15962 of sequences that is produced by the %p conversion of the corresponding fwprintf( ) 15963 functions. The application shall ensure that the corresponding argument is a pointer to 15964 a pointer to void. The interpretation of the input item is implementation-defined. If the | 15965 input item is a value converted earlier during the same program execution, the pointer 15966 that results shall compare equal to that value; otherwise, the behavior of the %p 15967 conversion is undefined. 15968 n No input is consumed. The application shall ensure that the corresponding argument is 15969 a pointer to the integer into which is to be written the number of wide characters read 15970 from the input so far by this call to the fwscanf( ) functions. Execution of a %n | 978 Technical Standard (2000) (Draft July 31, 2000) System Interfaces fwscanf( ) 15971 conversion specification does not increment the assignment count returned at the | 15972 completion of execution of the function. No argument is converted, but one is | 15973 consumed. If the conversion specification includes an assignment-suppressing wide | 15974 character or a field width, the behavior is undefined. | 15975 XSI C Same as lc. 15976 !S Same as ls. 15977 % Matches a single '%'; no conversion or assignment occurs. The complete conversion 15978 specification shall be "%%". 15979 If a conversion specification is invalid, the behavior is undefined. 15980 The conversion characters A, E, F, G, and X are also valid and behave the same as, respectively, a, | 15981 e, f, g, and x. | 15982 If end-of-file is encountered during input, conversion is terminated. If end-of-file occurs before 15983 any wide characters matching the current conversion specification (except for %n) have been 15984 read (other than leading white-space, where permitted), execution of the current conversion 15985 specification terminates with an input failure. Otherwise, unless execution of the current 15986 conversion specification is terminated with a matching failure, execution of the following 15987 conversion specification (if any) is terminated with an input failure. 15988 Reaching the end of the string in swscanf( ) is equivalent to encountering end-of-file for fwscanf( ). 15989 If conversion terminates on a conflicting input, the offending input is left unread in the input. 15990 Any trailing white space (including ) is left unread unless matched by a conversion 15991 specification. The success of literal matches and suppressed assignments is only directly 15992 determinable via the %n conversion specification. 15993 The fwscanf( ) and wscanf( ) functions may mark the st_atime field of the file associated with 15994 stream for update. The st_atime field shall be marked for update by the first successful execution 15995 of fgetc( ), fgetwc( ), fgets( ), fgetws( ), fread( ), getc( ), getwc( ), getchar( ), getwchar( ), gets( ), fscanf( ), 15996 or fwscanf( ) using stream that returns data not supplied by a prior call to ungetc( ). 15997 RETURN VALUE 15998 Upon successful completion, these functions shall return the number of successfully matched 15999 and assigned input items; this number can be 0 in the event of an early matching failure. If the 16000 input ends before the first matching failure or conversion, EOF shall be returned. If a read error 16001 CX occurs the error indicator for the stream is set, EOF shall be returned, and errno shall be set to 16002 indicate the error. 16003 ERRORS 16004 For the conditions under which the fwscanf( ) functions shall fail and may fail, refer to fgetwc( ). 16005 In addition, fwscanf( ) may fail if: 16006 XSI [EILSEQ] Input byte sequence does not form a valid character. | 16007 XSI [EINVAL] There are insufficient arguments. | System Interfaces, Issue 6 979 fwscanf( ) System Interfaces 16008 EXAMPLES 16009 The call: 16010 int i, n; float x; char name[50]; 16011 n = wscanf(L"%d%f%s", &i, &x, name); 16012 with the input line: 16013 25 54.32E-1 Hamster 16014 assigns to n the value 3, to i the value 25, to x the value 5.432, and name contains the string 16015 "Hamster". 16016 The call: 16017 int i; float x; char name[50]; 16018 (void) wscanf(L"%2d%f%*d %[0123456789]", &i, &x, name); 16019 with input: 16020 56789 0123 56a72 16021 assigns 56 to i, 789.0 to x, skip 0123, and place the string "56\0" in name. The next call to 16022 getchar( ) shall return the character 'a'. 16023 APPLICATION USAGE 16024 In format strings containing the '%' form of conversion specifications, each argument in the 16025 argument list is used exactly once. 16026 RATIONALE 16027 None. 16028 FUTURE DIRECTIONS 16029 None. 16030 SEE ALSO 16031 getwc( ), fwprintf( ), setlocale( ), wcstod( ), wcstol( ), wcstoul( ), wcrtomb( ), the Base Definitions | 16032 volume of IEEE Std. 1003.1-200x, , , , the Base Definitions | 16033 volume of IEEE Std. 1003.1-200x, Chapter 7, Locale | 16034 CHANGE HISTORY 16035 First released in Issue 5. Included for alignment with ISO/IEC 9899: 1990/Amendment 1: 1995 16036 (E). 16037 Issue 6 16038 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. | 16039 The following changes are made for alignment with the ISO/IEC 9899: 1999 standard: | 16040 * The prototypes for fwscanf( ) and swscanf( ) are updated. || 16041 * The DESCRIPTION is updated. | 980 Technical Standard (2000) (Draft July 31, 2000) System Interfaces gai_strerror( ) 16042 NAME 16043 gai_strerror - address and name information error description 16044 SYNOPSIS 16045 #include 16046 char *gai_strerror(int ecode); 16047 DESCRIPTION 16048 The gai_strerror( ) function shall return a text string describing an error that is listed in the 16049 header. 16050 When the ecode argument is one of the values listed in the header, the function return 16051 value points to a string describing the error. If the argument is not one of those values, the 16052 function shall return a pointer to a string whose contents indicate an unknown error. 16053 RETURN VALUE 16054 Upon successful completion, gai_strerror( ) shall return a pointer to an implementation-defined | 16055 string. | 16056 ERRORS 16057 No errors are defined. 16058 EXAMPLES 16059 None. 16060 APPLICATION USAGE 16061 None. 16062 RATIONALE 16063 None. 16064 FUTURE DIRECTIONS 16065 None. 16066 SEE ALSO 16067 getaddrinfo( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 16068 CHANGE HISTORY 16069 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. | System Interfaces, Issue 6 981 gcvt( ) System Interfaces 16070 NAME 16071 gcvt - convert a floating-point number to a string (LEGACY) 16072 SYNOPSIS 16073 XSI #include 16074 char *gcvt(double value, int ndigit, char *buf); 16075 16076 DESCRIPTION 16077 Refer to ecvt( ). 982 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getaddrinfo( ) 16078 NAME 16079 getaddrinfo - get address information 16080 SYNOPSIS 16081 #include 16082 #include 16083 int getaddrinfo(const char *restrict nodename, | 16084 const char *restrict servname, | 16085 const struct addrinfo *restrict hints, | 16086 struct addrinfo **restrict res); | 16087 DESCRIPTION | 16088 Refer to freeaddrinfo( ). System Interfaces, Issue 6 983 getc( ) System Interfaces 16089 NAME 16090 getc - get a byte from a stream 16091 SYNOPSIS 16092 #include 16093 int getc(FILE *stream); 16094 DESCRIPTION 16095 CX The functionality described on this reference page is aligned with the ISO C standard. Any 16096 conflict between the requirements described here and the ISO C standard is unintentional. This 16097 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 16098 The getc( ) function shall be equivalent to fgetc( ), except that if it is implemented as a macro it 16099 may evaluate stream more than once, so the argument should never be an expression with side 16100 effects. 16101 RETURN VALUE 16102 Refer to fgetc( ). 16103 ERRORS 16104 Refer to fgetc( ). 16105 EXAMPLES 16106 None. 16107 APPLICATION USAGE 16108 If the integer value returned by getc( ) is stored into a variable of type char and then compared 16109 against the integer constant EOF, the comparison may never succeed, because sign-extension of 16110 a variable of type char on widening to integer is implementation-defined. | 16111 Because it may be implemented as a macro, getc( ) may treat incorrectly a stream argument with 16112 side effects. In particular, getc(*f++) does not necessarily work as expected. Therefore, use of this 16113 function should be preceded by "#undef getc" in such situations; fgetc( ) could also be used. 16114 RATIONALE 16115 None. 16116 FUTURE DIRECTIONS 16117 None. 16118 SEE ALSO 16119 fgetc( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 16120 CHANGE HISTORY 16121 First released in Issue 1. Derived from Issue 1 of the SVID. | 16122 Issue 4 16123 The words ``a character variable'' are replaced by ``a variable of type char'', to emphasize the fact 16124 that this function deals with byte values. 16125 The APPLICATION USAGE section now states that the use of this function is not recommended. 984 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getc_unlocked( ) 16126 NAME 16127 getc_unlocked, getchar_unlocked, putc_unlocked, putchar_unlocked - stdio with explicit client 16128 locking 16129 SYNOPSIS 16130 TSF #include 16131 int getc_unlocked(FILE *stream); 16132 int getchar_unlocked(void); 16133 int putc_unlocked(int c, FILE *stream); 16134 int putchar_unlocked(int c); 16135 16136 DESCRIPTION 16137 Versions of the functions getc( ), getchar( ), putc( ), and putchar( ) respectively named 16138 getc_unlocked( ), getchar_unlocked( ), putc_unlocked( ), and putchar_unlocked( ) shall be provided 16139 which are functionally identical to the original versions, with the exception that they are not 16140 required to be implemented in a thread-safe manner. They may only safely be used within a 16141 scope protected by flockfile ( ) (or ftrylockfile ( )) and funlockfile ( ). These functions may safely be 16142 used in a multi-threaded program if and only if they are called while the invoking thread owns 16143 the (FILE*) object, as is the case after a successful call of the flockfile ( ) or ftrylockfile ( ) functions. 16144 RETURN VALUE 16145 See getc( ), getchar( ), putc( ), and putchar( ). 16146 ERRORS 16147 No errors are defined. 16148 EXAMPLES 16149 None. 16150 APPLICATION USAGE 16151 Because they may be implemented as macros, getc_unlocked( ) and putc_unlocked( ) may treat 16152 incorrectly a stream argument with side effects. In particular, getc_unlocked(*f++) and 16153 putc_unlocked(*f++) do not necessarily work as expected. Therefore, use of these functions in 16154 such situations should be preceded by the following statement as appropriate: 16155 #undef getc_unlocked 16156 #undef putc_unlocked 16157 RATIONALE 16158 Some I/O functions are typically implemented as macros for performance reasons (for example, 16159 putc( ) and getc( )). For safety, they need to be synchronized, but it is often too expensive to 16160 synchronize on every character. Nevertheless, it was felt that the safety concerns were more 16161 important; consequently, the getc( ), getchar( ), putc( ), and putchar( ) functions are required to be 16162 thread-safe. However, unlocked versions are also provided with names that clearly indicate the 16163 unsafe nature of their operation but can be used to exploit their higher performance. These 16164 unlocked versions can be safely used only within explicitly locked program regions, using 16165 exported locking primitives. In particular, a sequence such as: 16166 flockfile(fileptr); 16167 putc_unlocked('1', fileptr); 16168 putc_unlocked('\n', fileptr); 16169 fprintf(fileptr, "Line 2\n"); 16170 funlockfile(fileptr); 16171 is permissible, and results in the text sequence: System Interfaces, Issue 6 985 getc_unlocked( ) System Interfaces 16172 1 16173 Line 2 16174 being printed without being interspersed with output from other threads. 16175 It would be wrong to have the standard names such as getc( ), putc( ), and so on, map to the 16176 ``faster, but unsafe'' rather than the ``slower, but safe'' versions. In either case, you would still 16177 want to inspect all uses of getc( ), putc( ), and so on, by hand when converting existing code. 16178 Choosing the safe bindings as the default, at least, results in correct code and maintains the 16179 ``atomicity at the function'' invariant. To do otherwise would introduce gratuitous 16180 synchronization errors into converted code. Other routines that modify the stdio (FILE*) 16181 structures or buffers are also safely synchronized. 16182 Note that there is no need for functions of the form getc_locked( ), putc_locked( ), and so on, since 16183 this is the functionality of getc( ), putc( ), et al. It would be inappropriate to use a feature test 16184 macro to switch a macro definition of getc( ) between getc_locked( ) and getc_unlocked( ), since the 16185 ISO C standard requires an actual function to exist, a function whose behavior could not be 16186 changed by the feature test macro. Also, providing both the xxx_locked( ) and xxx_unlocked( ) 16187 forms leads to the confusion of whether the suffix describes the behavior of the function or the 16188 circumstances under which it should be used. 16189 Three additional routines, flockfile ( ), ftrylockfile ( ), and funlockfile ( ) (which may be macros), are 16190 provided to allow the user to delineate a sequence of I/O statements that are executed 16191 synchronously. 16192 The ungetc( ) function is infrequently called relative to the other functions/macros so no 16193 unlocked variation is needed. 16194 FUTURE DIRECTIONS 16195 None. 16196 SEE ALSO 16197 getc( ), getchar( ), putc( ), putchar( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 16198 16199 CHANGE HISTORY 16200 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 16201 Issue 6 16202 These functions are marked as part of the Thread-Safe Functions option. | 16203 The Open Group corrigenda item U030/2 has been applied adding APPLICATION USAGE 16204 describing how applications should be written to avoid the case when the functions are 16205 implemented as macros. 986 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getchar( ) 16206 NAME 16207 getchar - get a byte from a stdin stream 16208 SYNOPSIS 16209 #include 16210 int getchar(void); 16211 DESCRIPTION 16212 CX The functionality described on this reference page is aligned with the ISO C standard. Any 16213 conflict between the requirements described here and the ISO C standard is unintentional. This 16214 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 16215 The getchar( ) function shall be equivalent to getc(stdin). 16216 RETURN VALUE 16217 Refer to fgetc( ). 16218 ERRORS 16219 Refer to fgetc( ). 16220 EXAMPLES 16221 None. 16222 APPLICATION USAGE 16223 If the integer value returned by getchar( ) is stored into a variable of type char and then 16224 compared against the integer constant EOF, the comparison may never succeed, because sign- 16225 extension of a variable of type char on widening to integer is implementation-defined. | 16226 RATIONALE 16227 None. 16228 FUTURE DIRECTIONS 16229 None. 16230 SEE ALSO 16231 getc( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 16232 CHANGE HISTORY 16233 First released in Issue 1. Derived from Issue 1 of the SVID. | 16234 Issue 4 16235 The words ``a character variable'' are replaced by ``a variable of type char'', to emphasize the fact 16236 that this function deals in byte values. 16237 The following change is incorporated for alignment with the ISO C standard: 16238 * The argument list is explicitly defined as void. System Interfaces, Issue 6 987 getcontext( ) System Interfaces 16239 NAME 16240 getcontext, setcontext - get and set current user context 16241 SYNOPSIS 16242 XSI #include 16243 int getcontext(ucontext_t *ucp); 16244 int setcontext(const ucontext_t *ucp); 16245 16246 DESCRIPTION 16247 The getcontext( ) function shall initialize the structure pointed to by ucp to the current user 16248 context of the calling thread. The ucontext_t type that ucp points to defines the user context and 16249 includes the contents of the calling thread's machine registers, the signal mask, and the current 16250 execution stack. 16251 The setcontext( ) function shall restore the user context pointed to by ucp. A successful call to 16252 setcontext( ) shall not return; program execution resumes at the point specified by the ucp 16253 argument passed to setcontext( ). The ucp argument should be created either by a prior call to 16254 getcontext( ) or makecontext( ), or by being passed as an argument to a signal handler. If the ucp 16255 argument was created with getcontext( ), program execution continues as if the corresponding 16256 call of getcontext( ) had just returned. If the ucp argument was created with makecontext( ), 16257 program execution continues with the function passed to makecontext( ). When that function 16258 returns, the thread shall continue as if after a call to setcontext( ) with the ucp argument that was 16259 input to makecontext( ). If the uc_link member of the ucontext_t structure pointed to by the ucp 16260 argument is equal to 0, then this context is the main context, and the thread shall exit when this 16261 context returns. The effects of passing a ucp argument obtained from any other source are 16262 unspecified. 16263 RETURN VALUE 16264 Upon successful completion, setcontext( ) shall not return and getcontext( ) shall return 0; 16265 otherwise, a value of -1 shall be returned. 16266 ERRORS 16267 No errors are defined. 16268 EXAMPLES 16269 None. 16270 APPLICATION USAGE 16271 When a signal handler is executed, the current user context is saved and a new context is 16272 created. If the thread leaves the signal handler via longjmp( ), then it is unspecified whether the 16273 context at the time of the corresponding setjmp( ) call is restored and thus whether future calls to 16274 getcontext( ) provide an accurate representation of the current context, since the context restored 16275 by longjmp( ) does not necessarily contain all the information that setcontext( ) requires. Signal 16276 handlers should use siglongjmp( ) or setcontext( ) instead. 16277 Portable applications should not modify or access the uc_mcontext member of ucontext_t. A 16278 portable application cannot assume that context includes any process-wide static data, possibly 16279 including errno. Users manipulating contexts should take care to handle these explicitly when 16280 required. 16281 Use of contexts to create alternate stacks is not defined by this volume of IEEE Std. 1003.1-200x. 988 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getcontext( ) 16282 RATIONALE 16283 None. 16284 FUTURE DIRECTIONS 16285 None. 16286 SEE ALSO 16287 bsd_signal( ), makecontext( ), setjmp( ), sigaction( ), sigaltstack( ), sigprocmask( ), sigsetjmp( ), the Base | 16288 Definitions volume of IEEE Std. 1003.1-200x, | 16289 CHANGE HISTORY 16290 First released in Issue 4, Version 2. 16291 Issue 5 16292 Moved from X/OPEN UNIX extension to BASE. 16293 The following sentence was removed from the DESCRIPTION: ``If the ucp argument was passed 16294 to a signal handler, program execution continues with the program instruction following the 16295 instruction interrupted by the signal.'' System Interfaces, Issue 6 989 getcwd( ) System Interfaces 16296 NAME 16297 getcwd - get the path name of the current working directory 16298 SYNOPSIS 16299 #include 16300 char *getcwd(char *buf, size_t size); 16301 DESCRIPTION 16302 The getcwd( ) function shall place an absolute path name of the current working directory in the 16303 array pointed to by buf, and return buf. The path name copied to the array shall contain no 16304 components that are symbolic links. The size argument is the size in bytes of the character array 16305 pointed to by the buf argument. If buf is a null pointer, the behavior of getcwd( ) is unspecified. | 16306 RETURN VALUE 16307 Upon successful completion, getcwd( ) shall return the buf argument. Otherwise, getcwd( ) shall 16308 return a null pointer and set errno to indicate the error. The contents of the array pointed to by 16309 buf are then undefined. 16310 ERRORS 16311 The getcwd( ) function shall fail if: 16312 [EINVAL] The size argument is 0. | 16313 [ERANGE] The size argument is greater than 0, but is smaller than the length of the path | 16314 name +1. 16315 The getcwd( ) function may fail if: 16316 [EACCES] Read or search permission was denied for a component of the path name. | 16317 [ENOMEM] Insufficient storage space is available. | 16318 EXAMPLES 16319 Determining the Absolute Path Name of the Current Working Directory 16320 The following example returns a pointer to an array that holds the absolute path name of the 16321 current working directory. The pointer is returned in the ptr variable, which points to the buf 16322 array where the path name is stored. 16323 #include 16324 #include 16325 ... 16326 long size; 16327 char *buf; 16328 char *ptr; 16329 size = pathconf(".", _PC_PATH_MAX); 16330 if ((buf = (char *)malloc((size_t)size)) != NULL) 16331 ptr = getcwd(buf, (size_t)size); 16332 ... 16333 APPLICATION USAGE 16334 None. | 990 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getcwd( ) 16335 RATIONALE 16336 Since the maximum path name length is arbitrary unless {PATH_MAX} is defined, an 16337 application generally cannot supply a buf with size {{PATH_MAX} +1}. 16338 Having getcwd( ) take no arguments and instead use the malloc( ) function to produce space for 16339 the returned argument was considered. The advantage is that getcwd( ) knows how big the 16340 working directory path name is and can allocate an appropriate amount of space. But the 16341 programmer would have to use the free( ) function to free the resulting object, or each use of 16342 getcwd( ) would further reduce the available memory. Also, malloc( ) and free( ) are used nowhere 16343 else in this volume of IEEE Std. 1003.1-200x. Finally, getcwd( ) is taken from the SVID where it 16344 has the two arguments used in this volume of IEEE Std. 1003.1-200x. 16345 The older function getwd( ) was rejected for use in this context because it had only a buffer 16346 argument and no size argument, and thus had no way to prevent overwriting the buffer, except 16347 to depend on the programmer to provide a large enough buffer. 16348 On some implementations, if buf is a null pointer, getcwd( ) may obtain size bytes of memory | 16349 using malloc( ). In this case, the pointer returned by getcwd( ) may be used as the argument in a | 16350 subsequent call to free( ). Invoking getcwd( ) with buf as a null pointer is not recommended in | 16351 portable applications. | 16352 If a program is operating in a directory where some (grand)parent directory does not permit 16353 reading, getcwd( ) may fail, as in most implementations it must read the directory to determine 16354 the name of the file. This can occur if search, but not read, permission is granted in an 16355 intermediate directory, or if the program is placed in that directory by some more privileged 16356 process (for example, login). Including the [EACCES] error condition makes the reporting of the | 16357 error consistent and warns the application writer that getcwd( ) can fail for reasons beyond the 16358 control of the application writer or user. Some implementations can avoid this occurrence (for 16359 example, by implementing getcwd( ) using pwd, where pwd is a set-user-root process), thus the 16360 error was made optional. 16361 Because this volume of IEEE Std. 1003.1-200x permits the addition of other errors, this would be 16362 a common addition and yet one that applications could not be expected to deal with without 16363 this addition. 16364 FUTURE DIRECTIONS 16365 None. 16366 SEE ALSO 16367 malloc( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 16368 CHANGE HISTORY 16369 First released in Issue 1. Derived from Issue 1 of the SVID. | 16370 Issue 4 16371 The header is added to the SYNOPSIS section. 16372 The [ENOMEM] error is marked as an extension. 16373 The words ``as this functionality may be subject to withdrawal'' have been deleted from the end 16374 of the last sentence in the APPLICATION USAGE section. 16375 The following change is incorporated for alignment with the ISO POSIX-1 standard: 16376 * The DESCRIPTION is changed to indicate that the effects of passing a null pointer in buf are 16377 undefined. System Interfaces, Issue 6 991 getcwd( ) System Interfaces 16378 Issue 6 16379 The following new requirements on POSIX implementations derive from alignment with the 16380 Single UNIX Specification: 16381 * The [ENOMEM] optional error condition is added. 992 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getdate( ) 16382 NAME 16383 getdate - convert user format date and time 16384 SYNOPSIS 16385 XSI #include 16386 struct tm *getdate(const char *string); 16387 16388 DESCRIPTION 16389 The getdate( ) function shall convert a string representation of a date or time into a broken-down 16390 time. 16391 The external variable or macro getdate_err is used by getdate( ) to return error values. 16392 Templates are used to parse and interpret the input string. The templates are contained in a text 16393 file identified by the environment variable DATEMSK. The DATEMSK variable should be set to 16394 indicate the full path name of the file that contains the templates. The first line in the template 16395 that matches the input specification is used for interpretation and conversion into the internal 16396 time format. 16397 The following field descriptors are supported: 16398 %% Same as '%'. 16399 %a Abbreviated weekday name. 16400 %A Full weekday name. 16401 %b Abbreviated month name. 16402 %B Full month name. 16403 %c Locale's appropriate date and time representation. 16404 %C Century number (00-99; leading zeros are permitted but not required). 16405 %d Day of month (01-31; the leading 0 is optional). 16406 %D Date as %m/%d/%y. 16407 %e Same as %d. 16408 %h Abbreviated month name. 16409 %H Hour (00-23). 16410 %I Hour (01-12). 16411 %m Month number (01-12). 16412 %M Minute (00-59). 16413 %n Same as . 16414 %p Locale's equivalent of either AM or PM. 16415 %r The locale's appropriate representation of time in AM and PM notation. In the POSIX 16416 locale, this is equivalent to %I:%M:%S %p. 16417 %R Time as %H:%M. 16418 %S Seconds (00-61). Leap seconds are allowed but are not predictable through use of 16419 algorithms. System Interfaces, Issue 6 993 getdate( ) System Interfaces 16420 %t Same as . 16421 %T Time as %H:%M:%S. 16422 %w Weekday number (Sunday = 0-6). 16423 %x Locale's appropriate date representation. 16424 %X Locale's appropriate time representation. 16425 %y Year within century. When a century is not otherwise specified, values in the range 16426 69-99 refer to years in the twentieth century (1969 to 1999 inclusive); values in the range 16427 00-68 refer to years in the twenty-first century (2000 to 2068 inclusive). 16428 %Y Year as ccyy (for example, 1994). 16429 %Z Timezone name or no characters if no timezone exists. If the timezone supplied by %Z 16430 is not the timezone that getdate( ) expects, an invalid input specification error shall 16431 result. The getdate( ) function calculates an expected timezone based on information 16432 supplied to the function (such as the hour, day, and month). 16433 The match between the template and input specification performed by getdate( ) is case- 16434 insensitive. 16435 The month and weekday names can consist of any combination of upper and lowercase letters. 16436 The process can request that the input date or time specification be in a specific language by 16437 setting the LC_TIME category (see setlocale( )). 16438 Leading 0s are not necessary for the descriptors that allow leading 0s. However, at most two 16439 digits are allowed for those descriptors, including leading 0s. Extra whitespace in either the 16440 template file or in string is ignored. 16441 The field descriptors %c, %x, and %X shall not be supported if they include unsupported field 16442 descriptors. 16443 The following rules apply for converting the input specification into the internal format: 16444 * If %Z is being scanned, then getdate( ) initializes the broken-down time to be the current time 16445 in the scanned timezone. Otherwise, it initializes the broken-down time based on the current 16446 local time as if localtime( ) had been called. 16447 * If only the weekday is given, today is assumed if the given day is equal to the current day 16448 and next week if it is less, 16449 * If only the month is given, the current month is assumed if the given month is equal to the 16450 current month and next year if it is less, and no year is given (the first day of month is 16451 assumed if no day is given), 16452 * If no hour, minute, and second are given the current hour, minute, and second are assumed, 16453 * If no date is given, today is assumed if the given hour is greater than the current hour and 16454 tomorrow is assumed if it is less. 16455 If a field descriptor specification in the DATEMSK file does not correspond to one of the field 16456 descriptors above, the behavior is unspecified. 16457 The getdate( ) function need not be reentrant. A function that is not required to be reentrant is not 16458 required to be thread-safe. 994 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getdate( ) 16459 RETURN VALUE 16460 Upon successful completion, getdate( ) shall return a pointer to a struct tm. Otherwise, it shall 16461 return a null pointer and set getdate_err to indicate the error. 16462 ERRORS 16463 The getdate( ) function shall fail in the following cases, setting getdate_err to the value shown in 16464 the list below. Any changes to errno are unspecified. 16465 1. The DATEMSK environment variable is null or undefined. 16466 2. The template file cannot be opened for reading. 16467 3. Failed to get file status information. 16468 4. The template file is not a regular file. 16469 5. An I/O error is encountered while reading the template file. 16470 6. Memory allocation failed (not enough memory available). 16471 7. There is no line in the template that matches the input. 16472 8. Invalid input specification. For example, February 31; or a time is specified that cannot be 16473 represented in a time_t (representing the time in seconds since the Epoch). 16474 EXAMPLES 16475 1. The following example shows the possible contents of a template: 16476 %m 16477 %A %B %d, %Y, %H:%M:%S 16478 %A 16479 %B 16480 %m/%d/%y %I %p 16481 %d,%m,%Y %H:%M 16482 at %A the %dst of %B in %Y 16483 run job at %I %p,%B %dnd 16484 %A den %d. %B %Y %H.%M Uhr 16485 2. The following are examples of valid input specifications for the template in Example 1: 16486 getdate("10/1/87 4 PM"); 16487 getdate("Friday"); 16488 getdate("Friday September 18, 1987, 10:30:30"); 16489 getdate("24,9,1986 10:30"); 16490 getdate("at monday the 1st of december in 1986"); 16491 getdate("run job at 3 PM, december 2nd"); 16492 If the LC_TIME category is set to a German locale that includes freitag as a weekday name 16493 and oktober as a month name, the following would be valid: 16494 getdate("freitag den 10. oktober 1986 10.30 Uhr"); 16495 3. The following example shows how local date and time specification can be defined in the 16496 template: System Interfaces, Issue 6 995 getdate( ) System Interfaces 16497 ____________________________________________________ 16498 _ Invocation Line in Template ___________________________________________________ 16499 getdate("11/27/86") %m/%d/%y 16500 getdate("27.11.86") %d.%m.%y 16501 getdate("86-11-27") %y-%m-%d 16502 _ getdate("Friday 12:00:00") %A %H:%M:%S ___________________________________________________ 16503 4. The following examples help to illustrate the above rules assuming that the current date is 16504 Mon Sep 22 12:19:47 EDT 1986 and the LC_TIME category is set to the default C locale: 16505 _________________________________________________________________ 16506 _ Input Line in Template Date ________________________________________________________________ 16507 Mon %a Mon Sep 22 12:19:47 EDT 1986 16508 Sun %a Sun Sep 28 12:19:47 EDT 1986 16509 Fri %a Fri Sep 26 12:19:47 EDT 1986 16510 September %B Mon Sep 1 12:19:47 EDT 1986 16511 January %B Thu Jan 1 12:19:47 EST 1987 16512 December %B Mon Dec 1 12:19:47 EST 1986 16513 Sep Mon %b %a Mon Sep 1 12:19:47 EDT 1986 16514 Jan Fri %b %a Fri Jan 2 12:19:47 EST 1987 16515 Dec Mon %b %a Mon Dec 1 12:19:47 EST 1986 16516 Jan Wed 1989 %b %a %Y Wed Jan 4 12:19:47 EST 1989 16517 Fri 9 %a %H Fri Sep 26 09:00:00 EDT 1986 16518 Feb 10:30 %b %H:%S Sun Feb 1 10:00:30 EST 1987 16519 10:30 %H:%M Tue Sep 23 10:30:00 EDT 1986 16520 _ 13:30 %H:%M Mon Sep 22 13:30:00 EDT 1986 ________________________________________________________________ 16521 APPLICATION USAGE 16522 Although historical versions of getdate( ) did not require that declare the external 16523 variable getdate_err, this volume of IEEE Std. 1003.1-200x does require it. The Open Group 16524 encourages applications to remove declarations of getdate_err and instead incorporate the 16525 declaration by including . 16526 Applications should use %Y (4-digit years) in preference to %y (2-digit years). 16527 RATIONALE 16528 None. 16529 FUTURE DIRECTIONS 16530 None. 16531 SEE ALSO 16532 ctime( ), localtime( ), setlocale( ), strftime( ), times( ), the Base Definitions volume of | 16533 IEEE Std. 1003.1-200x, | 16534 CHANGE HISTORY 16535 First released in Issue 4, Version 2. 16536 Issue 5 16537 Moved from X/OPEN UNIX extension to BASE. 16538 The last paragraph of the DESCRIPTION is added. 16539 The %C specifier is added, and the exact meaning of the %y specifier is clarified in the 16540 DESCRIPTION. 16541 A note indicating that this function need not be reentrant is added to the DESCRIPTION. 996 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getdate( ) 16542 The %R specifier is changed to follow historical practice. 16543 Issue 6 16544 The DESCRIPTION is updated to refer to ``seconds since the Epoch'' rather than ``seconds since 16545 00:00:00 UTC (Coordinated Universal Time), January 1 1970'' for consistency with other time | 16546 functions. System Interfaces, Issue 6 997 getegid( ) System Interfaces 16547 NAME 16548 getegid - get the effective group ID 16549 SYNOPSIS 16550 #include 16551 gid_t getegid(void); 16552 DESCRIPTION 16553 The getegid( ) function shall return the effective group ID of the calling process. 16554 RETURN VALUE 16555 The getegid( ) function is always successful and no return value is reserved to indicate an error. 16556 ERRORS 16557 No errors are defined. 16558 EXAMPLES 16559 None. 16560 APPLICATION USAGE 16561 None. 16562 RATIONALE 16563 None. 16564 FUTURE DIRECTIONS 16565 None. 16566 SEE ALSO 16567 geteuid( ), getgid( ), getuid( ), setegid( ), seteuid( ), setgid( ), setregid( ), setreuid( ), setuid( ), the Base | 16568 Definitions volume of IEEE Std. 1003.1-200x, , | 16569 CHANGE HISTORY 16570 First released in Issue 1. Derived from Issue 1 of the SVID. | 16571 Issue 4 16572 The header is now marked as optional (OH); this header need not be included on 16573 XSI-conformant systems. 16574 The header is added to the SYNOPSIS section. 16575 The following change is incorporated for alignment with the ISO POSIX-1 standard: 16576 * The argument list is explicitly defined as void. 16577 Issue 6 16578 In the SYNOPSIS, the inclusion of is no longer required. 16579 The following new requirements on POSIX implementations derive from alignment with the 16580 Single UNIX Specification: 16581 * The requirement to include has been removed. Although was 16582 required for conforming implementations of previous POSIX specifications, it was not 16583 required for UNIX applications. 998 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getenv( ) 16584 NAME 16585 getenv - get value of an environment variable 16586 SYNOPSIS 16587 #include 16588 char *getenv(const char *name); 16589 DESCRIPTION 16590 CX The functionality described on this reference page is aligned with the ISO C standard. Any 16591 conflict between the requirements described here and the ISO C standard is unintentional. This 16592 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 16593 The getenv( ) function shall search the environment of the calling process (see the Base | 16594 Definitions volume of IEEE Std. 1003.1-200x, Chapter 8, Environment Variables) for the | 16595 environment variable name if it exists and return a pointer to the value of the environment | 16596 variable. If the specified environment variable cannot be found, a null pointer shall be returned. 16597 The application shall ensure that it does not modify the string pointed to by the getenv( ) 16598 function. The string pointed to may be overwritten by a subsequent call to getenv( ), setenv( ), 16599 XSI unsetenv( ), or putenv( )but shall not be overwritten by a call to any other function in this volume 16600 of IEEE Std. 1003.1-200x. 16601 If the application modifies environ or the pointers to which it points, the behavior of getenv( ) is 16602 undefined. 16603 CX The getenv( ) function need not be reentrant. A function that is not required to be reentrant is not 16604 required to be thread-safe. 16605 RETURN VALUE 16606 Upon successful completion, getenv( ) shall return a pointer to a string containing the value for 16607 the specified name. If the specified name cannot be found in the environment of the calling 16608 process, a null pointer shall be returned. 16609 The return value from getenv( ) may point to static data which may be overwritten by 16610 XSI subsequent calls to getenv( ), setenv( ), unsetenv( ), or putenv( ). 16611 ERRORS 16612 No errors are defined. 16613 EXAMPLES 16614 Getting the Value of an Environment Variable 16615 The following example gets the value of the HOME environment variable. 16616 #include 16617 ... 16618 const char *name = "HOME"; 16619 char *value; 16620 value = getenv(name); 16621 APPLICATION USAGE 16622 None. 16623 RATIONALE 16624 The clearenv( ) function was considered but rejected. The putenv( ) function has now been | 16625 included for alignment with the Single UNIX Specification. System Interfaces, Issue 6 999 getenv( ) System Interfaces 16626 The getenv( ) function is inherently not reentrant because it returns a value pointing to static 16627 data. 16628 Conforming applications are required not to modify environ directly, but to use only the 16629 functions described here to manipulate the process environment as an abstract object. Thus, the 16630 implementation of the environment access functions has complete control over the data 16631 structure used to represent the environment (subject to the requirement that environ be 16632 maintained as a list of strings with embedded equal signs for applications that wish to scan the 16633 environment). This constraint allows the implementation to properly manage the memory it 16634 allocates, either by using allocated storage for all variables (copying them on the first invocation 16635 of setenv( ) or unsetenv( )), or keeping track of which strings are currently in allocated space and 16636 which are not, via a separate table or some other means. This enables the implementation to free 16637 any allocated space used by strings (and perhaps the pointers to them) stored in environ when 16638 unsetenv( ) is called. A C runtime start-up procedure (that which invokes main( ) and perhaps 16639 initializes environ) can also initialize a flag indicating that none of the environment has yet been 16640 copied to allocated storage, or that the separate table has not yet been initialized. 16641 In fact, for higher performance of getenv( ), the implementation could also maintain a separate 16642 copy of the environment in a data structure that could be searched much more quickly (such as 16643 an indexed hash table, or a binary tree), and update both it and the linear list at environ when 16644 setenv( ) or unsetenv( ) is invoked. 16645 Performance of getenv( ) can be important for applications which have large numbers of 16646 environment variables. Typically, applications like this use the environment as a resource 16647 database of user-configurable parameters. The fact that these variables are in the user's shell 16648 environment usually means that any other program that uses environment variables (such as ls, 16649 which attempts to use COLUMNS, or really almost any utility (LANG, LC_ALL, and so on) is 16650 similarly slowed down by the linear search through the variables. 16651 An implementation that maintains separate data structures, or even one that manages the 16652 memory it consumes, is not currently required as it was thought it would reduce consensus 16653 among implementors who do not want to change their historical implementations. 16654 The POSIX Threads Extension states that multi-threaded applications must not modify environ 16655 directly, and that IEEE Std. 1003.1-200x is providing functions which such applications can use 16656 in the future to manipulate the environment in a thread-safe manner. Thus, moving away from 16657 application use of environ is desirable from that standpoint as well. 16658 FUTURE DIRECTIONS 16659 None. 16660 SEE ALSO 16661 exec, putenv( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , the Base | 16662 Definitions volume of IEEE Std. 1003.1-200x, Chapter 8, Environment Variables | 16663 CHANGE HISTORY 16664 First released in Issue 1. Derived from Issue 1 of the SVID. | 16665 Issue 4 16666 The DESCRIPTION is updated to indicate that the return string must not be modified by an 16667 application, may be overwritten by subsequent calls to getenv( ) or putenv( ), and is not 16668 overwritten by calls to other XSI system interfaces. 16669 A reference to putenv( ) has also been added to the APPLICATION USAGE section. 16670 The following change is incorporated for alignment with the ISO POSIX-1 standard: 1000 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getenv( ) 16671 * The type of argument name is changed from char* to const char*. 16672 Issue 5 16673 Normative text previously in the APPLICATION USAGE section is moved to the RETURN 16674 VALUE section. 16675 A note indicating that this function need not be reentrant is added to the DESCRIPTION. 16676 Issue 6 16677 The following changes were made to align with the IEEE P1003.1a draft standard: 16678 * References added to the new setenv( ) and unsetenv( ) functions. 16679 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1001 geteuid( ) System Interfaces 16680 NAME 16681 geteuid - get the effective user ID 16682 SYNOPSIS 16683 #include 16684 uid_t geteuid(void); 16685 DESCRIPTION 16686 The geteuid( ) function shall return the effective user ID of the calling process. 16687 RETURN VALUE 16688 The geteuid( ) function is always successful and no return value is reserved to indicate an error. 16689 ERRORS 16690 No errors are defined. 16691 EXAMPLES 16692 None. 16693 APPLICATION USAGE 16694 None. 16695 RATIONALE 16696 None. 16697 FUTURE DIRECTIONS 16698 None. 16699 SEE ALSO 16700 getegid( ), getgid( ), getuid( ), setegid( ), seteuid( ), setgid( ), setregid( ), setreuid( ), setuid( ), the Base | 16701 Definitions volume of IEEE Std. 1003.1-200x, , | 16702 CHANGE HISTORY 16703 First released in Issue 1. Derived from Issue 1 of the SVID. | 16704 Issue 4 16705 The header is now marked as optional (OH); this header need not be included on 16706 XSI-conformant systems. 16707 The header is added to the SYNOPSIS section. 16708 The following change is incorporated for alignment with the ISO POSIX-1 standard: 16709 * The argument list is explicitly defined as void. 16710 Issue 6 16711 In the SYNOPSIS, the inclusion of is no longer required. 16712 The following new requirements on POSIX implementations derive from alignment with the 16713 Single UNIX Specification: 16714 * The requirement to include has been removed. Although was 16715 required for conforming implementations of previous POSIX specifications, it was not 16716 required for UNIX applications. 1002 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getgid( ) 16717 NAME 16718 getgid - get the real group ID 16719 SYNOPSIS 16720 #include 16721 gid_t getgid(void); 16722 DESCRIPTION 16723 The getgid( ) function shall return the real group ID of the calling process. 16724 RETURN VALUE 16725 The getgid( ) function is always successful and no return value is reserved to indicate an error. 16726 ERRORS 16727 No errors are defined. 16728 EXAMPLES 16729 None. 16730 APPLICATION USAGE 16731 None. 16732 RATIONALE 16733 None. 16734 FUTURE DIRECTIONS 16735 None. 16736 SEE ALSO 16737 getegid( ), geteuid( ), getuid( ), setegid( ), seteuid( ), setgid( ), setregid( ), setreuid( ), setuid( ), the Base | 16738 Definitions volume of IEEE Std. 1003.1-200x, , | 16739 CHANGE HISTORY 16740 First released in Issue 1. Derived from Issue 1 of the SVID. | 16741 Issue 4 16742 The header is now marked as optional (OH); this header need not be included on 16743 XSI-conformant systems. 16744 The header is added to the SYNOPSIS section. 16745 The following change is incorporated for alignment with the ISO POSIX-1 standard: 16746 * The argument list is explicitly defined as void. 16747 Issue 6 16748 In the SYNOPSIS, the inclusion of is no longer required. 16749 The following new requirements on POSIX implementations derive from alignment with the 16750 Single UNIX Specification: 16751 * The requirement to include has been removed. Although was 16752 required for conforming implementations of previous POSIX specifications, it was not 16753 required for UNIX applications. System Interfaces, Issue 6 1003 getgrent( ) System Interfaces 16754 NAME 16755 getgrent - get the group database entry 16756 SYNOPSIS 16757 XSI #include 16758 struct group *getgrent(void); 16759 16760 DESCRIPTION 16761 Refer to endgrent( ). 1004 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getgrgid( ) 16762 NAME 16763 getgrgid, getgrgid_r - get group database entry for a group ID 16764 SYNOPSIS 16765 #include 16766 struct group *getgrgid(gid_t gid); 16767 TSF int getgrgid_r(gid_t gid, struct group *grp, char *buffer, 16768 size_t bufsize, struct group **result); 16769 16770 DESCRIPTION 16771 The getgrgid( ) function shall search the group database for an entry with a matching gid. 16772 The getgrgid( ) function need not be reentrant. A function that is not required to be reentrant is 16773 not required to be thread-safe. 16774 TSF The getgrgid_r( ) function updates the group structure pointed to by grp and stores a pointer to 16775 that structure at the location pointed to by result. The structure contains an entry from the 16776 group database with a matching gid. Storage referenced by the group structure is allocated from 16777 the memory provided with the buffer parameter, which is bufsize characters in size. The 16778 maximum size needed for this buffer can be determined with the {_SC_GETGR_R_SIZE_MAX} 16779 sysconf( ) parameter. A NULL pointer is returned at the location pointed to by result on error or if 16780 the requested entry is not found. 16781 RETURN VALUE 16782 Upon successful completion, getgrgid( ) shall return a pointer to a struct group with the structure 16783 defined in with a matching entry if one is found. The getgrgid( ) function shall return a 16784 null pointer if either the requested entry was not found, or an error occurred. On error, errno | 16785 shall be set to indicate the error. | 16786 The return value may point to a static area which is overwritten by a subsequent call to 16787 getgrent( ), getgrgid( ), or getgrnam( ). 16788 TSF If successful, the getgrgid_r( ) function shall return zero; otherwise, an error number shall be 16789 returned to indicate the error. 16790 ERRORS 16791 The getgrgid( ) and getgrgid_r( ) functions may fail if: | 16792 [EIO] An I/O error has occurred. | 16793 [EINTR] A signal was caught during getgrgid( ). | 16794 [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. | 16795 [ENFILE] The maximum allowable number of files is currently open in the system. | 16796 TSF The getgrgid_r( ) function may fail if: 16797 TSF [ERANGE] Insufficient storage was supplied via buffer and bufsize to contain the data to | 16798 be referenced by the resulting group structure. System Interfaces, Issue 6 1005 getgrgid( ) System Interfaces 16799 EXAMPLES 16800 Finding an Entry in the Group Database 16801 The following example uses getgrgid( ) to search the group database for a group ID that was 16802 previously stored in a stat structure, then prints out the group name if it is found. If the group is 16803 not found, the program prints the numeric value of the group for the entry. 16804 #include 16805 #include 16806 #include 16807 ... 16808 struct stat statbuf; 16809 struct group *grp; 16810 ... 16811 if ((grp = getgrgid(statbuf.st_gid)) != NULL) 16812 printf(" %-8.8s", grp->gr_name); 16813 else 16814 printf(" %-8d", statbuf.st_gid); 16815 ... 16816 APPLICATION USAGE 16817 Applications wishing to check for error situations should set errno to 0 before calling getgrgid( ). 16818 If errno is set on return, an error occurred. 16819 The getgrgid_r( ) function is thread-safe and shall return values in a user-supplied buffer instead 16820 of possibly using a static data area that may be overwritten by each call. 16821 RATIONALE 16822 None. 16823 FUTURE DIRECTIONS 16824 None. 16825 SEE ALSO 16826 endgrent( ), getgrnam( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , | 16827 , 16828 CHANGE HISTORY 16829 First released in Issue 1. Derived from System V Release 2.0. | 16830 Issue 4 16831 The DESCRIPTION is clarified. 16832 In the RETURN VALUE section, the reference to the setting of errno is marked as an extension. 16833 The errors [EIO], [EINTR], [EMFILE], and [ENFILE] are marked as extensions. 16834 A note is added to the APPLICATION USAGE section advising how applications should check 16835 for errors. 16836 The header is added as optional (OH); this header need not be included on XSI- 16837 conformant systems. 16838 Issue 5 16839 Normative text previously in the APPLICATION USAGE section is moved to the RETURN 16840 VALUE section. 16841 The getgrgid_r( ) function is included for alignment with the POSIX Threads Extension. 1006 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getgrgid( ) 16842 A note indicating that the getgrgid( ) function need not be reentrant is added to the 16843 DESCRIPTION. 16844 Issue 6 16845 The getgrgid_r( ) function is marked as part of the Thread-Safe Functions option. | 16846 The Open Group corrigenda item U028/3 has been applied correcting text in the DESCRIPTION 16847 describing matching the gid. 16848 In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. 16849 In the SYNOPSIS, the inclusion of is no longer required. 16850 The following new requirements on POSIX implementations derive from alignment with the 16851 Single UNIX Specification: 16852 * The requirement to include has been removed. Although was 16853 required for conforming implementations of previous POSIX specifications, it was not 16854 required for UNIX applications. 16855 * In the RETURN VALUE section, the requirement to set errno on error is added. 16856 * The [EIO], [EINTR], [EMFILE], and [ENFILE] optional error conditions are added. 16857 The APPLICATION USAGE section is updated to include a note on the thread-safe function and 16858 its avoidance of possibly using a static data area. System Interfaces, Issue 6 1007 getgrnam( ) System Interfaces 16859 NAME 16860 getgrnam, getgrnam_r - search group database for a name 16861 SYNOPSIS 16862 #include 16863 struct group *getgrnam(const char *name); 16864 TSF int getgrnam_r(const char *name, struct group *grp, char *buffer, 16865 size_t bufsize, struct group **result); 16866 16867 DESCRIPTION 16868 The getgrnam( ) function shall search the group database for an entry with a matching name. 16869 The getgrnam( ) function need not be reentrant. A function that is not required to be reentrant is 16870 not required to be thread-safe. 16871 TSF The getgrnam_r( ) function updates the group structure pointed to by grp and stores a pointer to 16872 that structure at the location pointed to by result. The structure contains an entry from the 16873 group database with a matching gid or name. Storage referenced by the group structure is 16874 allocated from the memory provided with the buffer parameter, which is bufsize characters in 16875 size. The maximum size needed for this buffer can be determined with the 16876 {_SC_GETGR_R_SIZE_MAX} sysconf( ) parameter. A NULL pointer is returned at the location 16877 pointed to by result on error or if the requested entry is not found. 16878 RETURN VALUE 16879 The getgrnam( ) function shall return a pointer to a struct group with the structure defined in 16880 with a matching entry if one is found. The getgrnam( ) function shall return a null 16881 pointer if either the requested entry was not found, or an error occurred. On error, errno shall be | 16882 set to indicate the error. | 16883 The return value may point to a static area which is overwritten by a subsequent call to 16884 getgrent( ), getgrgid( ), or getgrnam( ). 16885 TSF If successful, the getgrnam_r( ) function shall return zero; otherwise, an error number shall be 16886 returned to indicate the error. 16887 ERRORS 16888 The getgrnam( ) and getgrnam_r( ) functions may fail if: | 16889 [EIO] An I/O error has occurred. | 16890 [EINTR] A signal was caught during getgrnam( ). | 16891 [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. | 16892 [ENFILE] The maximum allowable number of files is currently open in the system. | 16893 The getgrnam_r( ) function may fail if: 16894 TSF [ERANGE] Insufficient storage was supplied via buffer and bufsize to contain the data to | 16895 be referenced by the resulting group structure. 1008 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getgrnam( ) 16896 EXAMPLES 16897 None. 16898 APPLICATION USAGE 16899 Applications wishing to check for error situations should set errno to 0 before calling getgrnam( ). 16900 If errno is set on return, an error occurred. 16901 The getgrnam_r( ) function is thread-safe and shall return values in a user-supplied buffer instead 16902 of possibly using a static data area that may be overwritten by each call. 16903 RATIONALE 16904 None. 16905 FUTURE DIRECTIONS 16906 None. 16907 SEE ALSO 16908 endgrent( ), getgrgid( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , , | 16909 16910 CHANGE HISTORY 16911 First released in Issue 1. Derived from System V Release 2.0. | 16912 Issue 4 16913 The DESCRIPTION is clarified. 16914 The header is added as optional (OH); this header need not be included on XSI- 16915 conformant systems. 16916 In the RETURN VALUE section, reference to the setting of errno is marked as an extension. 16917 The errors [EIO], [EINTR], [EMFILE], and [ENFILE] are marked as extensions. 16918 A note is added to the APPLICATION USAGE section advising how applications should check 16919 for errors. 16920 The following change is incorporated for alignment with the ISO POSIX-1 standard: 16921 * The type of argument name is changed from char* to const char*. 16922 Issue 5 16923 Normative text previously in the APPLICATION USAGE section is moved to the RETURN 16924 VALUE section. 16925 The getgrnam_r( ) function is included for alignment with the POSIX Threads Extension. 16926 A note indicating that the getgrnam( ) function need not be reentrant is added to the 16927 DESCRIPTION. 16928 Issue 6 16929 The getgrnam_r( ) function is marked as part of the Thread-Safe Functions option. | 16930 In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. 16931 In the SYNOPSIS, the inclusion of is no longer required. 16932 The following new requirements on POSIX implementations derive from alignment with the 16933 Single UNIX Specification: 16934 * The requirement to include has been removed. Although was 16935 required for conforming implementations of previous POSIX specifications, it was not 16936 required for UNIX applications. System Interfaces, Issue 6 1009 getgrnam( ) System Interfaces 16937 * In the RETURN VALUE section, the requirement to set errno on error is added. 16938 * The [EIO], [EINTR], [EMFILE], and [ENFILE] optional error conditions are added. 16939 The APPLICATION USAGE section is updated to include a note on the thread-safe function and 16940 its avoidance of possibly using a static data area. 1010 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getgroups( ) 16941 NAME 16942 getgroups - get supplementary group IDs 16943 SYNOPSIS 16944 #include 16945 int getgroups(int gidsetsize, gid_t grouplist[]); 16946 DESCRIPTION 16947 The getgroups( ) function fills in the array grouplist with the current supplementary group IDs of 16948 the calling process. It is implementation-defined whether getgroups( ) also returns the effective | 16949 group ID in the grouplist array. 16950 The gidsetsize argument specifies the number of elements in the array grouplist. The actual 16951 number of group IDs stored in the array is returned. The values of array entries with indices 16952 greater than or equal to the value returned are undefined. 16953 If gidsetsize is 0, getgroups( ) shall return the number of group IDs that it would otherwise return 16954 without modifying the array pointed to by grouplist. 16955 If the effective group ID of the process is returned with the supplementary group IDs, the value 16956 returned shall always be greater than or equal to one and less than or equal to the value of 16957 {NGROUPS_MAX}+1. | 16958 RETURN VALUE 16959 Upon successful completion, the number of supplementary group IDs shall be returned. A 16960 return value of -1 indicates failure and errno shall be set to indicate the error. 16961 ERRORS 16962 The getgroups( ) function shall fail if: 16963 [EINVAL] The gidsetsize argument is non-zero and less than the number of group IDs | 16964 that would have been returned. | 16965 EXAMPLES 16966 Getting the Supplementary Group IDs of the Calling Process 16967 The following example places the current supplementary group IDs of the calling process into 16968 the group array. 16969 #include 16970 #include 16971 ... 16972 gid_t *group; 16973 int nogroups; 16974 long ngroups_max; 16975 ngroups_max = sysconf(_SC_NGROUPS_MAX); 16976 group = (gid_t *)malloc(ngroups_max *sizeof(gid_t)); 16977 ngroups = getgroups(ngroups_max, group); 16978 APPLICATION USAGE 16979 None. 16980 RATIONALE 16981 The related function setgroups( ) is a privileged operation and therefore is not covered by this 16982 volume of IEEE Std. 1003.1-200x. System Interfaces, Issue 6 1011 getgroups( ) System Interfaces 16983 As implied by the definition of supplementary groups, the effective group ID may appear in the 16984 array returned by getgroups( ) or it may be returned only by getegid( ). Duplication may exist, but 16985 the application needs to call getegid( ) to be sure of getting all of the information. Various 16986 implementation variations and administrative sequences cause the set of groups appearing in 16987 the result of getgroups( ) to vary in order and as to whether the effective group ID is included, 16988 even when the set of groups is the same (in the mathematical sense of ``set''). (The history of a 16989 process and its parents could affect the details of result.) 16990 Applications writers should note that {NGROUPS_MAX} is not necessarily a constant on all 16991 implementations. 16992 FUTURE DIRECTIONS 16993 None. 16994 SEE ALSO 16995 getegid( ), setgid( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , | 16996 16997 CHANGE HISTORY 16998 First released in Issue 3. 16999 Entry included for alignment with the POSIX.1-1988 standard. 17000 Issue 4 17001 The header is now marked as optional (OH); this header need not be included on 17002 XSI-conformant systems. 17003 The header is added to the SYNOPSIS section. 17004 The following change is incorporated for alignment with the FIPS requirements: 17005 * A return value of 0 is no longer permitted, because {NGROUPS_MAX} cannot be 0. 17006 Issue 5 17007 Normative text previously in the APPLICATION USAGE section is moved to the 17008 DESCRIPTION. 17009 Issue 6 17010 In the SYNOPSIS, the inclusion of is no longer required. 17011 The following new requirements on POSIX implementations derive from alignment with the 17012 Single UNIX Specification: 17013 * The requirement to include has been removed. Although was 17014 required for conforming implementations of previous POSIX specifications, it was not 17015 required for UNIX applications. 17016 * A return value of 0 is not permitted, because {NGROUPS_MAX} cannot be 0. This is a FIPS 17017 requirement. 17018 The following changes were made to align with the IEEE P1003.1a draft standard: 17019 * Explanation added that the effective group ID may be included in the supplementary group 17020 list. 1012 Technical Standard (2000) (Draft July 31, 2000) System Interfaces gethostbyaddr( ) 17021 NAME 17022 gethostbyaddr (LEGACY), gethostbyname (LEGACY), getipnodebyaddr, getipnodebyname, - 17023 network host database functions 17024 SYNOPSIS 17025 #include 17026 struct hostent *gethostbyaddr(const void *addr, socklen_t len, 17027 int type); 17028 struct hostent *gethostbyname(const char *name); 17029 struct hostent *getipnodebyaddr(const void *restrict addr, socklen_t len,| 17030 int type, int *restrict error_num); | 17031 struct hostent *getipnodebyname(const char *name, int type, int flags, | 17032 int *error_num); 17033 DESCRIPTION 17034 These functions enable applications to retrieve information about hosts. This information is 17035 considered to be stored in a database that can be accessed sequentially or randomly. 17036 Implementation of this database is unspecified. 17037 Note: In many cases it is implemented by the Domain Name System, as documented in 17038 RFC 1034, RFC 1035, and RFC 1886. 17039 Entries are returned in hostent structures. 17040 The gethostbyaddr( ) function shall return an entry containing addresses of address family type for 17041 the host with address addr. len contains the length of the address pointed to by addr. The 17042 gethostbyaddr( ) function need not be reentrant. A function that is not required to be reentrant is 17043 not required to be thread-safe. 17044 The gethostbyname( ) function shall return an entry containing addresses of address family 17045 AF_INET for the host with name name. The gethostbyname( ) function need not be reentrant. A 17046 function that is not required to be reentrant is not required to be thread-safe. 17047 The getipnodebyaddr( ) function shall return the entry containing addresses of address family type 17048 for the host with address addr, opening a connection to the database if necessary. The len 17049 argument contains the length of the address pointed to by addr. If an error occurs, the 17050 appropriate error code is returned in error_num. The getipnodebyaddr( ) function is thread-safe. 17051 The getipnodebyname( ) function shall return the entry containing addresses of address family 17052 type for the host with name name, opening a connection to the database if necessary. The flags 17053 argument affects what information is returned. If an error occurs, the appropriate error code is 17054 returned in error_num. The getipnodebyname( ) function is thread-safe. 17055 The addr argument of gethostbyaddr( ) or getipnodebyaddr( ) shall be an in_addr structure when 17056 IP6 type is AF_INET, and shall be an in6_addr structure when type is AF_INET6. It contains a binary 17057 format (that is, not null-terminated) address in network byte order. The gethostbyaddr( ) function 17058 is not guaranteed to return addresses of address families other than AF_INET, even when such 17059 addresses exist in the database. 17060 If gethostbyaddr( ) or getipnodebyaddr( ) returns a record, then its h_addrtype field is the same as the 17061 type argument that was passed to the function, and its h_addr_list field lists a single address that 17062 IP6 is a copy of the addr argument that was passed to the function. If type is AF_INET6 and addr is 17063 an IPv4-mapped IPv6 address or an IPv4-compatible IPv6 address, then the h_name and h_aliases 17064 fields are those that would have been returned for address family AF_INET and address equal to 17065 the last four bytes of addr. System Interfaces, Issue 6 1013 gethostbyaddr( ) System Interfaces 17066 If gethostbyaddr( ) or getipnodebyaddr( ) are called with addr containing the IPv6 unspecified 17067 address (all bytes zero), then no query is performed and the function fails with 17068 [HOST_NOT_FOUND]. 17069 The name argument of getipnodebyname( ) shall be either a node name or a numeric address 17070 string. For IPv4, a numeric address string shall be in the dotted-decimal notation described in 17071 IP6 inet_addr( ). For IPv6, a numeric address string shall be in one of the standard IPv6 text forms 17072 described in inet_ntop( ) The name argument of gethostbyname( ) shall be a node name; the | 17073 behavior of gethostbyname( ) when passed a numeric address string is unspecified. 17074 IP6 If name is a dotted-decimal IPv4 address and af equals AF_INET, or name is an IPv6 hex address 17075 and af equals AF_INET6,the members of the returned hostent structure are as follows: 17076 h_name Points to a copy of the name argument. 17077 h_aliases A NULL pointer. 17078 h_addrtype A copy of the type argument. 17079 IP6 h_length Either 4 (for AF_INET) or 16 (for AF_INET6). 17080 IP6 h_addr_list[0] A pointer to the 4-byte or 16-byte binary address. 17081 h_addr_list[1] A NULL pointer. 17082 IP6 If name is a dotted-decimal IPv4 address and af equals AF_INET6 and AI_V4MAPPED is set in 17083 flags, an IPv4-mapped IPv6 address is returned, and the members are as follows: 17084 h_name Points to an IPv6 hex address containing the IPv4-mapped IPv6 address. 17085 h_aliases A NULL pointer. 17086 h_addrtype AF_INET6. 17087 h_length 16. 17088 h_addr_list[0] A pointer to the 16-byte binary address. 17089 h_addr_list[1] A NULL pointer. 17090 If name is a dotted-decimal IPv4 address and af equals AF_INET6 and AI_V4MAPPED is not set, 17091 then NULL is returned with [HOST_NOT_FOUND]. 17092 It is an error when name is an IPv6 hex address and af equals AF_INET. The function's return 17093 value is a NULL pointer with the [HOST_NOT_FOUND] error. 17094 If name is not a numeric address string and is an alias for a valid host name, then gethostbyname( ) 17095 or getipnodebyname( ) return information about the host name to which the alias refers, and name 17096 is included in the list of aliases returned. 17097 If name is a node name, then operation of the getipnodebyname( ) function is modified by the value 17098 of the flags argument, as follows: 17099 * If flags is 0 and type is AF_INET, then a query is made for IPv4 addresses. If it is successful, 17100 the IPv4 addresses are returned and the h_length member of the hostent structure shall have 17101 IP6 a value of 4. Otherwise, the function shall return a NULL pointer. 17102 * If flags is 0 and if type is AF_INET6, then a query is made for IPv6 addresses. If it is successful, 17103 the IPv6 addresses are returned and the h_length member of the hostent structure shall have 17104 a value of 16. If unsuccessful, the function shall return a NULL pointer. 17105 * If the AI_V4MAPPED flag is set and type is AF_INET6, then a query is made for IPv6 17106 addresses. If it is successful, the IPv6 addresses are returned, and no query is made for IPv4 1014 Technical Standard (2000) (Draft July 31, 2000) System Interfaces gethostbyaddr( ) 17107 addresses. If it is not successful, a query is made for IPv4 addresses and any found are 17108 returned as IPv4-mapped IPv6 addresses. h_length shall have a value of 16 in either case of 17109 addresses being returned. The AI_V4MAPPED flag is ignored unless type is AF_INET6. 17110 * If the AI_ALL and AI_V4MAPPED flags are both set and type is AF_INET6, then a query is 17111 made for IPv6 addresses, and any found are returned. Another query is then made for IPv4 17112 addresses, and any found are returned as IPv4-mapped IPv6 addresses, and h_length is 16. 17113 Only if both queries fail does the function return a NULL pointer. This flag is ignored unless 17114 type is AF_INET6. 17115 * The AI_ADDRCONFIG flag specifies that a query for IPv6 addresses should be made only if 17116 the node has at least one IPv6 source address configured, and that a query for IPv4 addresses 17117 should be made only if the node has at least one IPv4 source address configured. 17118 * If the AI_V4MAPPED and AI_ADDRCONFIG flags are both set and type is AF_INET6, then: 17119 - If the node has at least one IPv6 source address configured, a query is made for IPv6 17120 addresses. 17121 - If it is successful, the IPv6 addresses are returned and no query is made for IPv4 17122 addresses. 17123 - If the node has no IPv6 source address configured, or if the query for IPv6 addresses is not 17124 successful, then if the node has at least one IPv4 source address configured, a query is 17125 made for IPv4 addresses and any found are returned as IPv4-mapped IPv6 addresses. 17126 h_length shall have a value of 16 in either case of addresses being returned. 17127 * Macro AI_DEFAULT is defined as the logical OR of AI_V4MAPPED and AI_ADDRCONFIG. 17128 Note: It is intended that setting flags to AI_DEFAULT be appropriate for most 17129 applications. 17130 RETURN VALUE 17131 Upon successful completion, these functions shall return a pointer to a hostent structure if the 17132 requested entry was found, and a null pointer if the end of the database was reached or the 17133 requested entry was not found. 17134 Upon unsuccessful completion, getipnodebyaddr( ) and getipnodebyname( ) shall set their error_num 17135 argument to indicate the error, while gethostbyaddr( ) and gethostbyname( ) shall set h_errno to 17136 indicate it. 17137 ERRORS 17138 These functions shall fail in the following cases. The getipnodebyaddr( ) and getipnodebyname( ) 17139 functions shall return the value shown in the list below in error_num; the gethostbyaddr( ) and 17140 gethostbyname( ) functions shall set h_errno to that value. Any changes to errno are unspecified. 17141 [HOST_NOT_FOUND] 17142 No such host is known. 17143 [NO_DATA] The server recognized the request and the name, but no address is available. 17144 Another type of request to the name server for the domain might return an 17145 answer. 17146 [NO_RECOVERY] 17147 An unexpected server failure occurred which cannot be recovered. 17148 [TRY_AGAIN] A temporary and possibly transient error occurred, such as a failure of a 17149 server to respond. System Interfaces, Issue 6 1015 gethostbyaddr( ) System Interfaces 17150 EXAMPLES 17151 None. 17152 APPLICATION USAGE 17153 The hostent structure returned by getipnodebyaddr( ) and getipnodebyname( ), and any structures 17154 pointed to from those structures, are dynamically allocated. Applications should call 17155 freehostent( ) to free the memory used by these structures. 17156 The gethostbyaddr( ), and gethostbyname( ) functions may return pointers to static data, which may 17157 be overwritten by subsequent calls to any of these functions. Applications shall not call 17158 freehostent( ) for this area. 17159 The getipnodebyaddr( ) function is preferred over the gethostbyaddr( ) function. 17160 The getipnodebyname( ) function is preferred over the gethostbyname( ) function. 17161 RATIONALE 17162 None. 17163 FUTURE DIRECTIONS 17164 The gethostbyaddr( ) and gethostbyname( ) functions may be withdrawn in a future version. 17165 SEE ALSO 17166 endhostent( ), freehostent( ), endservent( ), inet_addr( ), the Base Definitions volume of | 17167 IEEE Std. 1003.1-200x, | 17168 CHANGE HISTORY 17169 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. | 17170 The restrict keyword is added to the getipnodebyaddr( ) prototype for alignment with the | 17171 ISO/IEC 9899: 1999 standard. | 1016 Technical Standard (2000) (Draft July 31, 2000) System Interfaces gethostbyname( ) 17172 NAME 17173 gethostbyname - network host database functions 17174 SYNOPSIS 17175 #include 17176 struct hostent *gethostbyname(const char *name); 17177 DESCRIPTION 17178 Refer to gethostbyaddr( ). System Interfaces, Issue 6 1017 gethostent( ) System Interfaces 17179 NAME 17180 gethostent - network host database functions 17181 SYNOPSIS 17182 #include 17183 struct hostent *gethostent(void); 17184 DESCRIPTION 17185 Refer to endhostent( ). 1018 Technical Standard (2000) (Draft July 31, 2000) System Interfaces gethostid( ) 17186 NAME 17187 gethostid - get an identifier for the current host 17188 SYNOPSIS 17189 XSI #include 17190 long gethostid(void); 17191 17192 DESCRIPTION 17193 The gethostid( ) function retrieves a 32-bit identifier for the current host. 17194 RETURN VALUE 17195 Upon successful completion, gethostid( ) shall return an identifier for the current host. 17196 ERRORS 17197 No errors are defined. 17198 EXAMPLES 17199 None. 17200 APPLICATION USAGE 17201 This volume of IEEE Std. 1003.1-200x does not define the domain in which the return value is 17202 unique. 17203 RATIONALE 17204 None. 17205 FUTURE DIRECTIONS 17206 None. 17207 SEE ALSO 17208 random( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 17209 CHANGE HISTORY 17210 First released in Issue 4, Version 2. 17211 Issue 5 17212 Moved from X/OPEN UNIX extension to BASE. System Interfaces, Issue 6 1019 gethostname( ) System Interfaces 17213 NAME 17214 gethostname - get name of current host 17215 SYNOPSIS 17216 #include 17217 int gethostname(char *name, socklen_t namelen); 17218 DESCRIPTION 17219 The gethostname( ) function shall return the standard host name for the current machine. The 17220 namelen argument shall specify the size of the array pointed to by the name argument. The 17221 returned name shall be null-terminated, except that if namelen is an insufficient length to hold 17222 the host name, then the returned name shall be truncated and it is unspecified whether the 17223 returned name is null-terminated. 17224 Host names are limited to 255 bytes. 17225 RETURN VALUE 17226 Upon successful completion, 0 shall be returned; otherwise, -1 shall be returned. 17227 ERRORS 17228 No errors are defined. 17229 EXAMPLES 17230 None. 17231 APPLICATION USAGE 17232 None. 17233 RATIONALE 17234 None. 17235 FUTURE DIRECTIONS 17236 None. 17237 SEE ALSO 17238 gethostid( ), uname( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 17239 CHANGE HISTORY 17240 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. | 1020 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getipnodebyaddr( ) 17241 NAME 17242 getipnodebyaddr - network host database functions 17243 SYNOPSIS 17244 #include 17245 struct hostent *getipnodebyaddr(const void *restrict addr, socklen_t len,| 17246 int type, int *restrict error_num); | 17247 DESCRIPTION | 17248 Refer to gethostbyaddr( ). System Interfaces, Issue 6 1021 getipnodebyname( ) System Interfaces 17249 NAME 17250 getipnodebyname - network host database functions 17251 SYNOPSIS 17252 #include 17253 struct hostent *getipnodebyname(const char *name, int type, int flags, 17254 int *error_num); 17255 DESCRIPTION 17256 Refer to gethostbyaddr( ). 1022 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getitimer( ) 17257 NAME 17258 getitimer, setitimer - get or set value of interval timer 17259 SYNOPSIS 17260 XSI #include 17261 int getitimer(int which, struct itimerval *value); 17262 int setitimer(int which, const struct itimerval *restrict value, | 17263 struct itimerval *restrict ovalue); | 17264 | 17265 DESCRIPTION 17266 The getitimer( ) function shall store the current value of the timer specified by which into the 17267 structure pointed to by value. The setitimer( ) function shall set the timer specified by which to 17268 the value specified in the structure pointed to by value, and if ovalue is not a null pointer, stores 17269 the previous value of the timer in the structure pointed to by ovalue. 17270 A timer value is defined by the itimerval structure, specified in . If it_value is non- 17271 zero, it shall indicate the time to the next timer expiration. If it_interval is non-zero, it shall 17272 specify a value to be used in reloading it_value when the timer expires. Setting it_value to 0 shall 17273 disable a timer, regardless of the value of it_interval. Setting it_interval to 0 shall disable a timer 17274 after its next expiration (assuming it_value is non-zero). 17275 Implementations may place limitations on the granularity of timer values. For each interval 17276 timer, if the requested timer value requires a finer granularity than the implementation supports, 17277 the actual timer value shall be rounded up to the next supported value. 17278 An XSI-conforming implementation provides each process with at least three interval timers, 17279 which are indicated by the which argument: 17280 ITIMER_REAL Decrements in real time. A SIGALRM signal is delivered when this timer 17281 expires. 17282 ITIMER_VIRTUAL Decrements in process virtual time. It runs only when the process is 17283 executing. A SIGVTALRM signal is delivered when it expires. 17284 ITIMER_PROF Decrements both in process virtual time and when the system is running 17285 on behalf of the process. It is designed to be used by interpreters in 17286 statistically profiling the execution of interpreted programs. Each time the 17287 ITIMER_PROF timer expires, the SIGPROF signal is delivered. 17288 The interaction between setitimer( ) and any of alarm( ), sleep( ), or usleep( ) is unspecified. 17289 RETURN VALUE 17290 Upon successful completion, getitimer( ) or setitimer( ) shall return 0; otherwise, -1 shall be 17291 returned and errno set to indicate the error. 17292 ERRORS 17293 The setitimer( ) function shall fail if: 17294 [EINVAL] The value argument is not in canonical form. (In canonical form, the number of | 17295 microseconds is a non-negative integer less than 1,000,000 and the number of 17296 seconds is a non-negative integer.) 17297 The getitimer( ) and setitimer( ) functions may fail if: 17298 [EINVAL] The which argument is not recognized. | System Interfaces, Issue 6 1023 getitimer( ) System Interfaces 17299 EXAMPLES 17300 None. 17301 APPLICATION USAGE 17302 None. 17303 RATIONALE 17304 None. 17305 FUTURE DIRECTIONS 17306 None. 17307 SEE ALSO 17308 alarm( ), sleep( ), timer_getoverrun( ), ualarm( ), usleep( ), the Base Definitions volume of | 17309 IEEE Std. 1003.1-200x, , | 17310 CHANGE HISTORY 17311 First released in Issue 4, Version 2. 17312 Issue 5 17313 Moved from X/OPEN UNIX extension to BASE. | 17314 Issue 6 | 17315 The restrict keyword is added to the setitimer( ) prototype for alignment with the | 17316 ISO/IEC 9899: 1999 standard. | 1024 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getlogin( ) 17317 NAME 17318 getlogin, getlogin_r - get login name 17319 SYNOPSIS 17320 #include 17321 char *getlogin(void); 17322 TSF int getlogin_r(char *name, size_t namesize); 17323 17324 DESCRIPTION 17325 The getlogin( ) function shall return a pointer to a string containing the user name associated by | 17326 the login activity with the controlling terminal of the current process. If getlogin( ) returns a non- | 17327 null pointer, then that pointer points to the name that the user logged in under, even if there are 17328 several login names with the same user ID. 17329 The getlogin( ) function need not be reentrant. A function that is not required to be reentrant is 17330 not required to be thread-safe. 17331 TSF The getlogin_r( ) function puts the name associated by the login activity with the controlling | 17332 terminal of the current process in the character array pointed to by name. The array is namesize | 17333 characters long and should have space for the name and the terminating null character. The 17334 maximum size of the login name is {LOGIN_NAME_MAX}. 17335 If getlogin_r( ) is successful, name points to the name the user used at login, even if there are 17336 several login names with the same user ID. 17337 RETURN VALUE 17338 Upon successful completion, getlogin( ) shall return a pointer to the login name or a null pointer 17339 if the user's login name cannot be found. Otherwise, it shall return a null pointer and set errno to | 17340 indicate the error. | 17341 The return value from getlogin( ) may point to static data whose content is overwritten by each 17342 call. 17343 TSF If successful, the getlogin_r( ) function shall return zero; otherwise, an error number shall be 17344 returned to indicate the error. 17345 ERRORS 17346 The getlogin( ) and getlogin_r( ) functions may fail if: | 17347 [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. | 17348 [ENFILE] The maximum allowable number of files is currently open in the system. | 17349 [ENXIO] The calling process has no controlling terminal. | 17350 The getlogin_r( ) function may fail if: 17351 TSF [ERANGE] The value of namesize is smaller than the length of the string to be returned | 17352 including the terminating null character. System Interfaces, Issue 6 1025 getlogin( ) System Interfaces 17353 EXAMPLES 17354 Getting the User Login Name 17355 The following example calls the getlogin( ) function to obtain the name of the user associated 17356 with the calling process, and passes this information to the getpwnam( ) function to get the 17357 associated user database information. 17358 #include 17359 #include 17360 #include 17361 #include 17362 ... 17363 char *lgn; 17364 struct passwd *pw; 17365 ... 17366 if ((lgn = getlogin()) == NULL || (pw = getpwnam(lgn)) == NULL) { 17367 fprintf(stderr, "Get of user information failed.\n"); exit(1); 17368 } 17369 APPLICATION USAGE 17370 Three names associated with the current process can be determined: getpwuid(geteuid( )) shall 17371 return the name associated with the effective user ID of the process; getlogin( ) shall return the 17372 name associated with the current login activity; and getpwuid(getuid( )) shall return the name 17373 associated with the real user ID of the process. 17374 The getlogin_r( ) function is thread-safe and shall return values in a user-supplied buffer instead 17375 of possibly using a static data area that may be overwritten by each call. 17376 RATIONALE 17377 The getlogin( ) function returns a pointer to the user's login name. The same user ID may be 17378 shared by several login names. If it is desired to get the user database entry that is used during 17379 login, the result of getlogin( ) should be used to provide the argument to the getpwnam( ) 17380 function. (This might be used to determine the user's login shell, particularly where a single user 17381 has multiple login shells with distinct login names, but the same user ID.) 17382 The information provided by the cuserid( ) function, which was originally defined in the 17383 POSIX.1-1988 standard and subsequently removed, can be obtained by the following: 17384 getpwuid(geteuid()) 17385 while the information provided by historical implementations of cuserid( ) can be obtained by: 17386 getpwuid(getuid()) 17387 The thread-safe version of this function places the user name in a user-supplied buffer and 17388 returns a non-zero value if it fails. The non-thread-safe version may return the name in a static 17389 data area that may be overwritten by each call. 17390 FUTURE DIRECTIONS 17391 None. 17392 SEE ALSO 17393 getpwnam( ), getpwuid( ), geteuid( ), getuid( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 17394 , 1026 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getlogin( ) 17395 CHANGE HISTORY 17396 First released in Issue 1. Derived from System V Release 2.0. | 17397 Issue 4 17398 The header is added to the SYNOPSIS section. 17399 In the RETURN VALUE section, reference to the setting of errno is marked as an extension. 17400 The behavior of the function when the login name cannot be found is included in the RETURN 17401 VALUE section instead of the DESCRIPTION. 17402 The errors [EMFILE], [ENFILE], and [ENXIO] are marked as extensions. 17403 The APPLICATION USAGE section is changed to refer to getpwuid( ) rather than cuserid( ), which 17404 may be withdrawn in a future version. 17405 The following changes are incorporated for alignment with the ISO POSIX-1 standard: 17406 * The argument list is explicitly defined as void. 17407 * The DESCRIPTION is updated to state explicitly that the return value is a pointer to a string 17408 giving the user name, rather than simply a pointer to the user name as stated in previous 17409 issues. 17410 Issue 5 17411 Normative text previously in the APPLICATION USAGE section is moved to the RETURN 17412 VALUE section. 17413 The getlogin_r( ) function is included for alignment with the POSIX Threads Extension. 17414 A note indicating that the getlogin( ) function need not be reentrant is added to the 17415 DESCRIPTION. 17416 Issue 6 17417 The getlogin_r( ) function is marked as part of the Thread-Safe Functions option. | 17418 In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. 17419 The following new requirements on POSIX implementations derive from alignment with the 17420 Single UNIX Specification: 17421 * In the RETURN VALUE section, the requirement to set errno on error is added. 17422 * The [EMFILE], [ENFILE], and [ENXIO] optional error conditions are added. 17423 The APPLICATION USAGE section is updated to include a note on the thread-safe function and 17424 its avoidance of possibly using a static data area. System Interfaces, Issue 6 1027 getmsg( ) System Interfaces 17425 NAME 17426 getmsg, getpmsg - receive next message from a STREAMS file (STREAMS) 17427 SYNOPSIS 17428 XSR #include 17429 int getmsg(int fildes, struct strbuf *restrict ctlptr, | 17430 struct strbuf *restrict dataptr, int *restrict flagsp); | 17431 int getpmsg(int fildes, struct strbuf *restrict ctlptr, | 17432 struct strbuf *restrict dataptr, int *restrict bandp, | 17433 int *restrict flagsp); | 17434 | 17435 DESCRIPTION 17436 The getmsg( ) function shall retrieve the contents of a message located at the head of the 17437 STREAM head read queue associated with a STREAMS file and place the contents into one or 17438 more buffers. The message contains either a data part, a control part, or both. The data and 17439 control parts of the message are placed into separate buffers, as described below. The semantics 17440 of each part are defined by the originator of the message. 17441 The getpmsg( ) function does the same thing as getmsg( ), but provides finer control over the 17442 priority of the messages received. Except where noted, all requirements on getmsg( ) also pertain 17443 to getpmsg( ). 17444 The fildes argument specifies a file descriptor referencing a STREAMS-based file. 17445 The ctlptr and dataptr arguments each point to a strbuf structure, in which the buf member points 17446 to a buffer in which the data or control information is to be placed, and the maxlen member 17447 indicates the maximum number of bytes this buffer can hold. On return, the len member 17448 contains the number of bytes of data or control information actually received. The len member is 17449 set to 0 if there is a zero-length control or data part and len is set to -1 if no data or control 17450 information is present in the message. 17451 When getmsg( ) is called, flagsp should point to an integer that indicates the type of message the 17452 process is able to receive. This is described further below. 17453 The ctlptr argument is used to hold the control part of the message, and dataptr is used to hold 17454 the data part of the message. If ctlptr (or dataptr) is a null pointer or the maxlen member is -1, the 17455 control (or data) part of the message is not processed and is left on the STREAM head read 17456 queue, and if the ctlptr (or dataptr) is not a null pointer, len is set to -1. If the maxlen member is 17457 set to 0 and there is a zero-length control (or data) part, that zero-length part is removed from 17458 the read queue and len is set to 0. If the maxlen member is set to 0 and there are more than 0 bytes 17459 of control (or data) information, that information is left on the read queue and len is set to 0. If 17460 the maxlen member in ctlptr (or dataptr) is less than the control (or data) part of the message, 17461 maxlen bytes are retrieved. In this case, the remainder of the message is left on the STREAM head 17462 read queue and a non-zero return value is provided. 17463 By default, getmsg( ) processes the first available message on the STREAM head read queue. 17464 However, a process may choose to retrieve only high-priority messages by setting the integer 17465 pointed to by flagsp to RS_HIPRI. In this case, getmsg( ) shall only process the next message if it is 17466 a high-priority message. When the integer pointed to by flagsp is 0, any message shall be 17467 retrieved. In this case, on return, the integer pointed to by flagsp is set to RS_HIPRI if a high- 17468 priority message was retrieved, or 0 otherwise. 17469 For getpmsg( ), the flags are different. The flagsp argument points to a bitmask with the following 17470 mutually-exclusive flags defined: MSG_HIPRI, MSG_BAND, and MSG_ANY. Like getmsg( ), 17471 getpmsg( ) processes the first available message on the STREAM head read queue. A process may 1028 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getmsg( ) 17472 choose to retrieve only high-priority messages by setting the integer pointed to by flagsp to 17473 MSG_HIPRI and the integer pointed to by bandp to 0. In this case, getpmsg( ) shall only process 17474 the next message if it is a high-priority message. In a similar manner, a process may choose to 17475 retrieve a message from a particular priority band by setting the integer pointed to by flagsp to 17476 MSG_BAND and the integer pointed to by bandp to the priority band of interest. In this case, 17477 getpmsg( ) shall only process the next message if it is in a priority band equal to, or greater than, 17478 the integer pointed to by bandp, or if it is a high-priority message. If a process just wants to get 17479 the first message off the queue, the integer pointed to by flagsp should be set to MSG_ANY and 17480 the integer pointed to by bandp should be set to 0. On return, if the message retrieved was a 17481 high-priority message, the integer pointed to by flagsp is set to MSG_HIPRI and the integer 17482 pointed to by bandp shall be set to 0. Otherwise, the integer pointed to by flagsp shall be set to 17483 MSG_BAND and the integer pointed to by bandp shall be set to the priority band of the message. 17484 If O_NONBLOCK is not set, getmsg( ) and getpmsg( ) shall block until a message of the type 17485 specified by flagsp is available at the front of the STREAM head read queue. If O_NONBLOCK is 17486 set and a message of the specified type is not present at the front of the read queue, getmsg( ) and 17487 getpmsg( ) shall fail and set errno to [EAGAIN]. 17488 If a hangup occurs on the STREAM from which messages are retrieved, getmsg( ) and getpmsg( ) 17489 continue to operate normally, as described above, until the STREAM head read queue is empty. 17490 Thereafter, they return 0 in the len members of ctlptr and dataptr. 17491 RETURN VALUE 17492 Upon successful completion, getmsg( ) and getpmsg( ) shall return a non-negative value. A value 17493 of 0 indicates that a full message was read successfully. A return value of MORECTL indicates 17494 that more control information is waiting for retrieval. A return value of MOREDATA indicates 17495 that more data is waiting for retrieval. A return value of the bitwise-logical OR of MORECTL 17496 and MOREDATA indicates that both types of information remain. Subsequent getmsg( ) and 17497 getpmsg( ) calls shall retrieve the remainder of the message. However, if a message of higher 17498 priority has come in on the STREAM head read queue, the next call to getmsg( ) or getpmsg( ) 17499 shall retrieve that higher-priority message before retrieving the remainder of the previous 17500 message. 17501 If the high priority control part of the message is consumed, the message shall be placed back on 17502 the queue as a normal message of band 0. Subsequent getmsg( ) and getpmsg( ) calls shall retrieve 17503 the remainder of the message. If, however, a priority message arrives or already exists on the 17504 STREAM head, the subsequent call to getmsg( ) or getpmsg( ) retrieves the higher-priority 17505 message before retrieving the remainder of the message that was put back. 17506 Upon failure, getmsg( ) and getpmsg( ) shall return -1 and set errno to indicate the error. 17507 ERRORS 17508 The getmsg( ) and getpmsg( ) functions shall fail if: 17509 [EAGAIN] The O_NONBLOCK flag is set and no messages are available. | 17510 [EBADF] The fildes argument is not a valid file descriptor open for reading. | 17511 [EBADMSG] The queued message to be read is not valid for getmsg( ) or getpmsg( ) or a | 17512 pending file descriptor is at the STREAM head. 17513 [EINTR] A signal was caught during getmsg( ) or getpmsg( ). | 17514 [EINVAL] An illegal value was specified by flagsp, or the STREAM or multiplexer | 17515 referenced by fildes is linked (directly or indirectly) downstream from a 17516 multiplexer. System Interfaces, Issue 6 1029 getmsg( ) System Interfaces 17517 [ENOSTR] A STREAM is not associated with fildes. | 17518 In addition, getmsg( ) and getpmsg( ) shall fail if the STREAM head had processed an 17519 asynchronous error before the call. In this case, the value of errno does not reflect the result of 17520 getmsg( ) or getpmsg( ) but reflects the prior error. 17521 EXAMPLES 17522 Getting Any Message 17523 In the following example, the value of fd is assumed to refer to an open STREAMS file. The call 17524 to getmsg( ) retrieves any available message on the associated STREAM-head read queue, 17525 returning control and data information to the buffers pointed to by ctrlbuf and databuf, 17526 respectively. 17527 #include 17528 ... 17529 int fd; 17530 char ctrlbuf[128]; 17531 char databuf[512]; 17532 struct strbuf ctrl; 17533 struct strbuf data; 17534 int flags = 0; 17535 int ret; 17536 ctrl.buf = ctrlbuf; 17537 ctrl.maxlen = sizeof(ctrlbuf); 17538 data.buf = databuf; 17539 data.maxlen = sizeof(databuf); 17540 ret = getmsg (fd, &ctrl, &data, &flags); 17541 Getting the First Message off the Queue 17542 In the following example, the call to getpmsg( ) retrieves the first available message on the 17543 associated STREAM-head read queue. 17544 #include 17545 ... 17546 int fd; 17547 char ctrlbuf[128]; 17548 char databuf[512]; 17549 struct strbuf ctrl; 17550 struct strbuf data; 17551 int band = 0; 17552 int flags = MSG_ANY; 17553 int ret; 17554 ctrl.buf = ctrlbuf; 17555 ctrl.maxlen = sizeof(ctrlbuf); 17556 data.buf = databuf; 17557 data.maxlen = sizeof(databuf); 17558 ret = getpmsg (fd, &ctrl, &data, &band, &flags); 1030 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getmsg( ) 17559 APPLICATION USAGE 17560 None. 17561 RATIONALE 17562 None. 17563 FUTURE DIRECTIONS 17564 None. 17565 SEE ALSO 17566 poll( ), putmsg( ), read( ), write( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 17567 , Section 2.6 (on page 539) 17568 CHANGE HISTORY 17569 First released in Issue 4, Version 2. 17570 Issue 5 17571 Moved from X/OPEN UNIX extension to BASE. 17572 A paragraph regarding ``high-priority control parts of messages'' is added to the RETURN 17573 VALUE section. 17574 Issue 6 17575 This function is marked as part of the XSI STREAMS Option Group. | 17576 The restrict keyword is added to the getmsg( ) and getpmsg( ) prototypes for alignment with the | 17577 ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 1031 getnameinfo( ) System Interfaces 17578 NAME 17579 getnameinfo - get name information 17580 Notes to Reviewers 17581 This section with side shading will not appear in the final copy. - Ed. 17582 The IPv6 developers believe that getnameinfo( ) should not truncate the result if the user buffer is 17583 too small, but return an error status. 17584 SYNOPSIS 17585 #include 17586 #include 17587 int getnameinfo(const struct sockaddr *restrict sa, socklen_t salen, | 17588 char *restrict node, socklen_t nodelen, char *restrict service, | 17589 socklen_t servicelen, unsigned flags); | 17590 DESCRIPTION | 17591 The getnameinfo( ) function translates a socket address to a node name and service location, all of 17592 which are defined as in getaddrinfo( ). 17593 The sa argument points to a socket address structure to be translated. 17594 If the node argument is non-NULL and the nodelen argument is non-zero, then the node argument 17595 points to a buffer able to contain up to nodelen characters that receives the node name as a null- 17596 terminated string. If the node argument is NULL or the nodelen argument is zero, the node name 17597 shall not be returned. If the node's name cannot be located, the numeric form of the node's 17598 address is returned instead of its name. 17599 If the service argument is non-NULL and the servicelen argument is non-zero, then the service 17600 argument points to a buffer able to contain up to servicelen characters that receives the service 17601 name as a null-terminated string. If the service argument is NULL or the servicelen argument is 17602 zero, the service name shall not be returned. If the service's name cannot be located, the numeric 17603 form of the service address (for example, its port number) is returned instead of its name. 17604 The node and service arguments cannot both be NULL. 17605 The flags argument is a flag that changes the default actions of the function. By default the fully- 17606 qualified domain name (FQDN) for the host is returned, but: 17607 * If the flag bit NI_NOFQDN is set, only the node name portion of the FQDN shall be returned 17608 for local hosts. 17609 * If the flag bit NI_NUMERICHOST is set, the numeric form of the host's address shall be 17610 returned instead of its name, under all circumstances. 17611 * If the flag bit NI_NAMEREQD is set, an error shall be returned if the host's name cannot be 17612 located. 17613 * If the flag bit NI_NUMERICSERV is set, the numeric form of the service address shall be 17614 returned (for example, its port number) instead of its name, under all circumstances. 17615 * If the flag bit NI_DGRAM is set, this indicates that the service is a datagram service 17616 (SOCK_DGRAM). The default behavior shall assume that the service is a stream service 17617 (SOCK_STREAM). 17618 Notes: 17619 1. The two NI_NUMERICxxx flags are required to support the -n flag that many 17620 commands provide. 1032 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getnameinfo( ) 17621 2. The NI_DGRAM flag is required for the few AF_INET and AF_INET6 port 17622 numbers (for example, 512-514) that represent different services for UDP and 17623 TCP. 17624 The getnameinfo( ) function shall be thread-safe. 17625 RETURN VALUE 17626 A zero return value for getnameinfo( ) indicates successful completion; a non-zero return value 17627 indicates failure. The possible values for the failures are listed in the ERRORS section. | 17628 Upon successful completion, getnameinfo( ) shall return the node and service names, if requested, 17629 in the buffers provided. The returned names are always null-terminated strings, and may be 17630 truncated if the actual values are longer than can be stored in the buffers provided. 17631 ERRORS 17632 The getnameinfo( ) function shall fail and return the corresponding value if: 17633 [EAI_AGAIN] The name could not be resolved at this time. Future attempts may succeed. 17634 [EAI_BADFLAGS] 17635 The flags had an invalid value. 17636 [EAI_FAIL] A non-recoverable error occurred. 17637 [EAI_FAMILY] The address family was not recognized or the address length was invalid for 17638 the specified family. 17639 [EAI_MEMORY] There was a memory allocation failure. 17640 [EAI_NONAME] The name does not resolve for the supplied parameters. 17641 NI_NAMEREQD is set and the host's name cannot be located, or both 17642 nodename and servname were null. 17643 [EAI_SYSTEM] A system error occurred. The error code can be found in errno. 17644 EXAMPLES 17645 None. 17646 APPLICATION USAGE 17647 If the returned values are to be used as part of any further name resolution (for example, passed 17648 to getaddrinfo( )), applications shall either provide buffers large enough to store any result 17649 possible on the system or shall check for truncation and handle that case appropriately. 17650 RATIONALE 17651 None. 17652 FUTURE DIRECTIONS 17653 None. 17654 SEE ALSO 17655 getaddrinfo( ), getservbyname( ), getservbyport( ), inet_ntop( ), socket( ), the Base Definitions volume | 17656 of IEEE Std. 1003.1-200x, , | 17657 CHANGE HISTORY 17658 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. | 17659 The restrict keyword is added to the getnameinfo( ) prototype for alignment with the | 17660 ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 1033 getnetbyaddr( ) System Interfaces 17661 NAME 17662 getnetbyaddr - network database functions 17663 SYNOPSIS 17664 #include 17665 struct netent *getnetbyaddr(uint32_t net, int type); 17666 DESCRIPTION 17667 Refer to endnetent( ). 1034 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getnetbyname( ) 17668 NAME 17669 getnetbyname - network database functions 17670 SYNOPSIS 17671 #include 17672 struct netent *getnetbyname(const char *name); 17673 DESCRIPTION 17674 Refer to endnetent( ). System Interfaces, Issue 6 1035 getnetent( ) System Interfaces 17675 NAME 17676 getnetent - network database functions 17677 SYNOPSIS 17678 #include 17679 struct netent *getnetent(void); 17680 DESCRIPTION 17681 Refer to endnetent( ). 1036 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getopt( ) 17682 NAME 17683 getopt, optarg, opterr, optind, optopt - command option parsing 17684 SYNOPSIS 17685 #include 17686 int getopt(int argc, char * const argv[], const char *optstring); 17687 extern char *optarg; 17688 extern int optind, opterr, optopt; 17689 DESCRIPTION 17690 The getopt( ) function is a command-line parser that can be used by applications that follow 17691 Utility Syntax Guidelines 3, 4, 5, 6, 7, 9, and 10 in the Base Definitions volume of | 17692 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. The remaining guidelines are not | 17693 addressed by getopt( ) and are the responsibility of the application. | 17694 The parameters argc and argv are the argument count and argument array as passed to main( ) 17695 (see exec). The argument optstring is a string of recognized option characters; if a character is 17696 followed by a colon, the option takes an argument. All option characters allowed by Utility 17697 Syntax Guideline 3 are allowed in optstring. The implementation may accept other characters as 17698 an extension. 17699 The variable optind is the index of the next element of the argv[] vector to be processed. It is 17700 initialized to 1 by the system, and getopt( ) updates it when it finishes with each element of 17701 argv[ ]. When an element of argv[ ] contains multiple option characters, it is unspecified how 17702 getopt( ) determines which options have already been processed. 17703 The getopt( ) function shall return the next option character (if one is found) from argv that 17704 matches a character in optstring, if there is one that matches. If the option takes an argument, 17705 getopt( ) shall set the variable optarg to point to the option-argument as follows: 17706 1. If the option was the last character in the string pointed to by an element of argv, then 17707 optarg contains the next element of argv, and optind is incremented by 2. If the resulting 17708 value of optind is greater than argc, this indicates a missing option-argument, and getopt( ) 17709 shall return an error indication. 17710 2. Otherwise, optarg points to the string following the option character in that element of 17711 argv, and optind is incremented by 1. 17712 If, when getopt( ) is called: 17713 argv[optind] is a null pointer 17714 *argv[optind] is not the character - 17715 argv[optind] points to the string "-" 17716 getopt( ) shall return -1 without changing optind. If: 17717 argv[optind] points to the string "--" 17718 getopt( ) shall return -1 after incrementing optind. 17719 If getopt( ) encounters an option character that is not contained in optstring, it shall return the 17720 question-mark ('?') character. If it detects a missing option-argument, it shall return the colon 17721 character (':') if the first character of optstring was a colon, or a question-mark character ('?') 17722 otherwise. In either case, getopt( ) shall set the variable optopt to the option character that caused 17723 the error. If the application has not set the variable opterr to 0 and the first character of optstring 17724 is not a colon, getopt( ) shall also print a diagnostic message to stderr in the format specified for 17725 the getopts utility. System Interfaces, Issue 6 1037 getopt( ) System Interfaces 17726 The getopt( ) function need not be reentrant. A function that is not required to be reentrant is not 17727 required to be thread-safe. 17728 RETURN VALUE 17729 The getopt( ) function shall return the next option character specified on the command line. 17730 A colon (':') shall be returned if getopt( ) detects a missing argument and the first character of 17731 optstring was a colon (':'). 17732 A question mark ('?') shall be returned if getopt( ) encounters an option character not in 17733 optstring or detects a missing argument and the first character of optstring was not a colon (':'). 17734 Otherwise, getopt( ) shall return -1 when all command line options are parsed. 17735 ERRORS 17736 No errors are defined. 17737 EXAMPLES 17738 Parsing Command Line Options 17739 The following code fragment shows how you might process the arguments for a utility that can 17740 take the mutually-exclusive options a and b and the options f and o, both of which require 17741 arguments: 17742 #include 17743 int 17744 main(int argc, char *argv[ ]) 17745 { 17746 int c; 17747 int bflg, aflg, errflg; 17748 char *ifile; 17749 char *ofile; 17750 extern char *optarg; 17751 extern int optind, optopt; 17752 . . . 17753 while ((c = getopt(argc, argv, ":abf:o:")) != -1) { 17754 switch(c) { 17755 case 'a': 17756 if (bflg) 17757 errflg++; 17758 else 17759 aflg++; 17760 break; 17761 case 'b': 17762 if (aflg) 17763 errflg++; 17764 else { 17765 bflg++; 17766 bproc(); 17767 } 17768 break; 17769 case 'f': 17770 ifile = optarg; 17771 break; 17772 case 'o': 1038 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getopt( ) 17773 ofile = optarg; 17774 break; 17775 case ':': /* -f or -o without operand */ 17776 fprintf(stderr, 17777 "Option -%c requires an operand\n", optopt); 17778 errflg++; 17779 break; 17780 case '?': 17781 fprintf(stderr, 17782 "Unrecognized option: -%c\n", optopt); 17783 errflg++; 17784 } 17785 } 17786 if (errflg) { 17787 fprintf(stderr, "usage: . . . "); 17788 exit(2); 17789 } 17790 for ( ; optind < argc; optind++) { 17791 if (access(argv[optind], R_OK)) { 17792 . . . 17793 } 17794 This code accepts any of the following as equivalent: 17795 cmd -ao arg path path 17796 cmd -a -o arg path path 17797 cmd -o arg -a path path 17798 cmd -a -o arg -- path path 17799 cmd -a -oarg path path 17800 cmd -aoarg path path 17801 Checking Options and Arguments 17802 The following example parses a set of command line options and prints messages to standard 17803 output for each option and argument that it encounters. 17804 #include 17805 #include 17806 ... 17807 int c; 17808 char *filename; 17809 extern char *optarg; 17810 extern int optind, optopt, opterr; 17811 ... 17812 while ((c = getopt(argc, argv, ":abf:")) != -1) { 17813 switch(c) { 17814 case 'a': 17815 printf("a is set\n"); 17816 break; 17817 case 'b': 17818 printf("b is set\n"); 17819 break; 17820 case 'f': 17821 filename = optarg; System Interfaces, Issue 6 1039 getopt( ) System Interfaces 17822 printf("filename is %s\n", filename); 17823 break; 17824 case ':': 17825 printf("-%c without filename\n", optopt); 17826 break; 17827 case '?': 17828 printf("unknown arg %c\n", optopt); 17829 break; 17830 } 17831 } 17832 Selecting Options from the Command Line 17833 The following example selects the type of database routines the user wants to use based on the 17834 Options argument. 17835 #include 17836 #include 17837 ... 17838 char *Options = "hdbtl"; 17839 ... 17840 int dbtype, i; 17841 char c; 17842 char *st; 17843 ... 17844 dbtype = 0; 17845 while ((c = getopt(argc, argv, Options)) != -1) { 17846 if ((st = strchr(Options, c)) != NULL) { 17847 dbtype = st - Options; 17848 break; 17849 } 17850 } 17851 APPLICATION USAGE 17852 The getopt( ) function is only required to support option characters included in Utility Syntax 17853 Guideline 3. Many historical implementations of getopt( ) support other characters as options. 17854 This is an allowed extension, but applications that use extensions are not maximally portable. 17855 Note that support for multi-byte option characters is only possible when such characters can be 17856 represented as type int. 17857 RATIONALE 17858 The optopt variable represents historical practice and allows the application to obtain the identity 17859 of the invalid option. 17860 The description has been written to make it clear that getopt( ), like the getopts utility, deals with 17861 option-arguments whether separated from the option by characters or not. Note that 17862 the requirements on getopt( ) and getopts are more stringent than the Utility Syntax Guidelines. 17863 The getopt( ) function shall return -1, rather than EOF, so that is not required. 17864 The special significance of a colon as the first character of optstring makes getopt( ) consistent 17865 with the getopts utility. It allows an application to make a distinction between a missing 17866 argument and an incorrect option letter without having to examine the option letter. It is true 17867 that a missing argument can only be detected in one case, but that is a case that has to be 17868 considered. 1040 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getopt( ) 17869 FUTURE DIRECTIONS 17870 None. 17871 SEE ALSO 17872 exec, the Base Definitions volume of IEEE Std. 1003.1-200x, , the Shell and Utilities | 17873 volume of IEEE Std. 1003.1-200x | 17874 CHANGE HISTORY 17875 First released in Issue 1. Derived from Issue 1 of the SVID. | 17876 Issue 4 17877 The following changes are incorporated for alignment with the ISO POSIX-2 standard: 17878 * The header is added to the SYNOPSIS section and is deleted. 17879 * The type of argument argv is changed from char** to char*const[ ]. 17880 * The integer optopt is added to the list of external data items. 17881 * The DESCRIPTION is largely rewritten, without functional change, for alignment with the 17882 ISO POSIX-2 standard, although the following differences should be noted: 17883 - If the function detects a missing option-argument, it returns a colon (':') and sets optopt 17884 to the option character. 17885 - The termination conditions under which getopt( ) returns -1 are extended. Also note that 17886 the termination condition is explicitly -1, rather than the value of EOF. 17887 * The EXAMPLES section is changed to illustrate the new functionality. 17888 Issue 5 17889 A note indicating that the getopt( ) function need not be reentrant is added to the DESCRIPTION. 17890 Issue 6 17891 IEEE PASC Interpretation 1003.2 #150 is applied. | System Interfaces, Issue 6 1041 getpeername( ) System Interfaces 17892 NAME 17893 getpeername - get the name of the peer socket 17894 SYNOPSIS 17895 #include 17896 int getpeername(int socket, struct sockaddr *restrict address, | 17897 socklen_t *address_len); | 17898 DESCRIPTION 17899 The getpeername( ) function shall retrieve the peer address of the specified socket, store this 17900 address in the sockaddr structure pointed to by the address argument, and store the length of this 17901 address in the object pointed to by the address_len argument. 17902 If the actual length of the address is greater than the length of the supplied sockaddr structure, 17903 the stored address shall be truncated. 17904 If the protocol permits connections by unbound clients, and the peer is not bound, then the value 17905 stored in the object pointed to by address is unspecified. 17906 RETURN VALUE 17907 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno set to 17908 indicate the error. 17909 ERRORS 17910 The getpeername( ) function shall fail if: 17911 [EBADF] The socket argument is not a valid file descriptor. | 17912 [EINVAL] The socket has been shut down. 17913 [ENOTCONN] The socket is not connected or otherwise has not had the peer prespecified. 17914 [ENOTSOCK] The socket argument does not refer to a socket. 17915 [EOPNOTSUPP] The operation is not supported for the socket protocol. 17916 The getpeername( ) function may fail if: 17917 [ENOBUFS] Insufficient resources were available in the system to complete the call. | 17918 EXAMPLES 17919 None. 17920 APPLICATION USAGE 17921 None. 17922 RATIONALE 17923 None. 17924 FUTURE DIRECTIONS 17925 None. 17926 SEE ALSO 17927 accept( ), bind( ), getsockname( ), socket( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 17928 17929 CHANGE HISTORY 17930 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. | 17931 The restrict keyword is added to the getpeername( ) prototype for alignment with the | 17932 ISO/IEC 9899: 1999 standard. | 1042 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getpgid( ) 17933 NAME 17934 getpgid - get the process group ID for a process | 17935 SYNOPSIS 17936 XSI #include 17937 pid_t getpgid(pid_t pid); 17938 17939 DESCRIPTION 17940 The getpgid( ) function shall return the process group ID of the process whose process ID is equal 17941 to pid. If pid is equal to 0, getpgid( ) shall return the process group ID of the calling process. 17942 RETURN VALUE 17943 Upon successful completion, getpgid( ) shall return a process group ID. Otherwise, it shall return 17944 (pid_t)-1 and set errno to indicate the error. 17945 ERRORS 17946 The getpgid( ) function shall fail if: 17947 [EPERM] The process whose process ID is equal to pid is not in the same session as the | 17948 calling process, and the implementation does not allow access to the process 17949 group ID of that process from the calling process. 17950 [ESRCH] There is no process with a process ID equal to pid. | 17951 The getpgid( ) function may fail if: 17952 [EINVAL] The value of the pid argument is invalid. | 17953 EXAMPLES 17954 None. 17955 APPLICATION USAGE 17956 None. 17957 RATIONALE 17958 None. 17959 FUTURE DIRECTIONS 17960 None. 17961 SEE ALSO 17962 exec, fork( ), getpgrp( ), getpid( ), getsid( ), setpgid( ), setsid( ), the Base Definitions volume of | 17963 IEEE Std. 1003.1-200x, | 17964 CHANGE HISTORY 17965 First released in Issue 4, Version 2. 17966 Issue 5 17967 Moved from X/OPEN UNIX extension to BASE. System Interfaces, Issue 6 1043 getpgrp( ) System Interfaces 17968 NAME 17969 getpgrp - get the process group ID of the calling process 17970 SYNOPSIS 17971 #include 17972 pid_t getpgrp(void); 17973 DESCRIPTION 17974 The getpgrp( ) function shall return the process group ID of the calling process. 17975 RETURN VALUE 17976 The getpgrp( ) function is always successful and no return value is reserved to indicate an error. 17977 ERRORS 17978 No errors are defined. 17979 EXAMPLES 17980 None. 17981 APPLICATION USAGE 17982 None. 17983 RATIONALE 17984 4.3 BSD provides a getpgrp( ) function that returns the process group ID for a specified process. 17985 Although this function is used to support job control, all known job control shells always specify 17986 the calling process with this function. Thus, the simpler System V getpgrp( ) suffices, and the 17987 added complexity of the 4.3 BSD getpgrp( ) has been omitted from this volume of 17988 IEEE Std. 1003.1-200x. 17989 FUTURE DIRECTIONS 17990 None. 17991 SEE ALSO 17992 exec, fork( ), getpgid( ), getpid( ), getppid( ), kill( ), setpgid( ), setsid( ), the Base Definitions volume of | 17993 IEEE Std. 1003.1-200x, , | 17994 CHANGE HISTORY 17995 First released in Issue 1. Derived from Issue 1 of the SVID. | 17996 Issue 4 17997 The header is now marked as optional (OH); this header need not be included on 17998 XSI-conformant systems. 17999 The header is added to the SYNOPSIS section. 18000 The following change is incorporated for alignment with the ISO POSIX-1 standard: 18001 * The argument list is explicitly defined as void. 18002 Issue 6 18003 In the SYNOPSIS, the inclusion of is no longer required. 18004 The following new requirements on POSIX implementations derive from alignment with the 18005 Single UNIX Specification: 18006 * The requirement to include has been removed. Although was 18007 required for conforming implementations of previous POSIX specifications, it was not 18008 required for UNIX applications. 1044 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getpid( ) 18009 NAME 18010 getpid - get the process ID 18011 SYNOPSIS 18012 #include 18013 pid_t getpid(void); 18014 DESCRIPTION 18015 The getpid( ) function shall return the process ID of the calling process. 18016 RETURN VALUE 18017 The getpid( ) function is always successful and no return value is reserved to indicate an error. 18018 ERRORS 18019 No errors are defined. 18020 EXAMPLES 18021 None. 18022 APPLICATION USAGE 18023 None. 18024 RATIONALE 18025 None. 18026 FUTURE DIRECTIONS 18027 None. 18028 SEE ALSO 18029 exec, fork( ), getpgrp( ), getppid( ), kill( ), setpgid( ), setsid( ), the Base Definitions volume of | 18030 IEEE Std. 1003.1-200x, , | 18031 CHANGE HISTORY 18032 First released in Issue 1. Derived from Issue 1 of the SVID. | 18033 Issue 4 18034 The header is now marked as optional (OH); this header need not be included on 18035 XSI-conformant systems. 18036 The header is added to the SYNOPSIS section. 18037 The following change is incorporated for alignment with the ISO POSIX-1 standard: 18038 * The argument list is explicitly defined as void. 18039 Issue 6 18040 In the SYNOPSIS, the inclusion of is no longer required. 18041 The following new requirements on POSIX implementations derive from alignment with the 18042 Single UNIX Specification: 18043 * The requirement to include has been removed. Although was 18044 required for conforming implementations of previous POSIX specifications, it was not 18045 required for UNIX applications. System Interfaces, Issue 6 1045 getpmsg( ) System Interfaces 18046 NAME 18047 getpmsg - receive next message from a STREAMS file 18048 SYNOPSIS 18049 XSI #include 18050 int getpmsg(int fildes, struct strbuf *restrict ctlptr, | 18051 struct strbuf *restrict dataptr, int *restrict bandp, | 18052 int *restrict flagsp); | 18053 | 18054 DESCRIPTION 18055 Refer to getmsg( ). 1046 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getppid( ) 18056 NAME 18057 getppid - get the parent process ID 18058 SYNOPSIS 18059 #include 18060 pid_t getppid(void); 18061 DESCRIPTION 18062 The getppid( ) function shall return the parent process ID of the calling process. 18063 RETURN VALUE 18064 The getppid( ) function is always successful and no return value is reserved to indicate an error. 18065 ERRORS 18066 No errors are defined. 18067 EXAMPLES 18068 None. 18069 APPLICATION USAGE 18070 None. 18071 RATIONALE 18072 None. 18073 FUTURE DIRECTIONS 18074 None. 18075 SEE ALSO 18076 exec, fork( ), getpgid( ), getpgrp( ), getpid( ), kill( ), setpgid( ), setsid( ), the Base Definitions volume of | 18077 IEEE Std. 1003.1-200x, , | 18078 CHANGE HISTORY 18079 First released in Issue 1. Derived from Issue 1 of the SVID. | 18080 Issue 4 18081 The header is now marked as optional (OH); this header need not be included on 18082 XSI-conformant systems. 18083 The header is added to the SYNOPSIS section. 18084 The following change is incorporated for alignment with the ISO POSIX-1 standard: 18085 * The argument list is explicitly defined as void. 18086 Issue 6 18087 In the SYNOPSIS, the inclusion of is no longer required. 18088 The following new requirements on POSIX implementations derive from alignment with the 18089 Single UNIX Specification: 18090 * The requirement to include has been removed. Although was 18091 required for conforming implementations of previous POSIX specifications, it was not 18092 required for UNIX applications. System Interfaces, Issue 6 1047 getpriority( ) System Interfaces 18093 NAME 18094 getpriority, setpriority - get or set the nice value 18095 SYNOPSIS 18096 XSI #include 18097 int getpriority(int which, id_t who); 18098 int setpriority(int which, id_t who, int value); 18099 18100 DESCRIPTION 18101 The getpriority( ) function obtains the nice value of a process, process group, or user. The 18102 setpriority( ) function sets the nice value of a process, process group, or user to value+ {NZERO}. 18103 Target processes are specified by the values of the which and who arguments. The which 18104 argument may be one of the following values: PRIO_PROCESS, PRIO_PGRP, or PRIO_USER, 18105 indicating that the who argument is to be interpreted as a process ID, a process group ID, or an 18106 effective user ID, respectively. A 0 value for the who argument specifies the current process, 18107 process group, or user. 18108 The nice value set with setpriority( ) shall be applied to the process. If the process is multi- 18109 threaded, the nice value shall affect all system scope threads in the process. 18110 If more than one process is specified, getpriority( ) shall return value {NZERO} less than the 18111 lowest nice value pertaining to any of the specified processes, and setpriority( ) sets the nice 18112 values of all of the specified processes to value+ {NZERO}. 18113 The default nice value is {NZERO}; lower nice values cause more favorable scheduling. While 18114 the range of valid nice values is [0,{NZERO}*2 -1], implementations may enforce more 18115 restrictive limits. If value+ {NZERO} is less than the system's lowest supported nice value, 18116 setpriority( ) sets the nice value to the lowest supported value; if value+ {NZERO} is greater than 18117 the system's highest supported nice value, setpriority( ) sets the nice value to the highest 18118 supported value. 18119 Only a process with appropriate privileges can lower its nice value. 18120 PS|TPS Any processes or threads using SCHED_FIFO or SCHED_RR are unaffected by a call to 18121 setpriority( ). This is not considered an error. 18122 The effect of changing the nice value may vary depending on the process-scheduling algorithm 18123 in effect. 18124 Because getpriority( ) can return the value -1 on successful completion, it is necessary to set errno 18125 to 0 prior to a call to getpriority( ). If getpriority( ) returns the value -1, then errno can be checked 18126 to see if an error occurred or if the value is a legitimate nice value. 18127 RETURN VALUE 18128 Upon successful completion, getpriority( ) shall return an integer in the range from -{NZERO} to 18129 {NZERO}-1. Otherwise, -1 shall be returned and errno set to indicate the error. 18130 Upon successful completion, setpriority( ) shall return 0; otherwise, -1 shall be returned and errno 18131 set to indicate the error. 18132 ERRORS 18133 The getpriority( ) and setpriority( ) functions shall fail if: 18134 [ESRCH] No process could be located using the which and who argument values | 18135 specified. 1048 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getpriority( ) 18136 [EINVAL] The value of the which argument was not recognized, or the value of the who | 18137 argument is not a valid process ID, process group ID, or user ID. 18138 In addition, setpriority( ) may fail if: 18139 [EPERM] A process was located, but neither the real nor effective user ID of the | 18140 executing process match the effective user ID of the process whose nice value 18141 is being changed. 18142 [EACCES] A request was made to change the nice value to a lower numeric value and | 18143 the current process does not have appropriate privileges. 18144 EXAMPLES 18145 Using getpriority( ) 18146 The following example returns the current scheduling priority for the process ID returned by the 18147 call to getpid( ). 18148 #include 18149 ... 18150 int which = PRIO_PROCESS; 18151 id_t pid; 18152 int ret; 18153 pid = getpid(); 18154 ret = getpriority(which, pid); 18155 Using setpriority( ) 18156 The following example sets the priority for the current process ID to -20. 18157 #include 18158 ... 18159 int which = PRIO_PROCESS; 18160 id_t pid; 18161 int priority = -20; 18162 int ret; 18163 pid = getpid(); 18164 ret = setpriority(which, pid, priority); 18165 APPLICATION USAGE 18166 The getpriority( ) and setpriority( ) functions work with an offset nice value (nice value 18167 -{NZERO}). The nice value is in the range [0,2*{NZERO} -1], while the return value for 18168 getpriority( ) and the third parameter for setpriority( ) are in the range [-{NZERO},{NZERO} -1]. 18169 RATIONALE 18170 None. 18171 FUTURE DIRECTIONS 18172 None. 18173 SEE ALSO 18174 nice( ), sched_get_priority_max( ), sched_setscheduler( ), the Base Definitions volume of | 18175 IEEE Std. 1003.1-200x, | System Interfaces, Issue 6 1049 getpriority( ) System Interfaces 18176 CHANGE HISTORY 18177 First released in Issue 4, Version 2. 18178 Issue 5 18179 Moved from X/OPEN UNIX extension to BASE. 18180 The DESCRIPTION is reworded in terms of the nice value rather than priority to avoid confusion 18181 with functionality in the POSIX Realtime Extension. 1050 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getprotobyname( ) 18182 NAME 18183 getprotobyname - network protocol database functions 18184 SYNOPSIS 18185 #include 18186 struct protoent *getprotobyname(const char *name); 18187 DESCRIPTION 18188 Refer to endprotoent( ). System Interfaces, Issue 6 1051 getprotobynumber( ) System Interfaces 18189 NAME 18190 getprotobynumber - network protocol database functions 18191 SYNOPSIS 18192 #include 18193 struct protoent *getprotobynumber(int proto); 18194 DESCRIPTION 18195 Refer to endprotoent( ). 1052 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getprotoent( ) 18196 NAME 18197 getprotoent - network protocol database functions 18198 SYNOPSIS 18199 #include 18200 struct protoent *getprotoent(void); 18201 DESCRIPTION 18202 Refer to endprotoent( ). System Interfaces, Issue 6 1053 getpwent( ) System Interfaces 18203 NAME 18204 getpwent - get user database entry 18205 SYNOPSIS 18206 XSI #include 18207 struct passwd *getpwent(void); 18208 18209 DESCRIPTION 18210 Refer to endpwent( ). 1054 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getpwnam( ) 18211 NAME 18212 getpwnam, getpwnam_r - search user database for a name 18213 SYNOPSIS 18214 #include 18215 struct passwd *getpwnam(const char *name); 18216 TSF int getpwnam_r(const char *name, struct passwd *pwd, char *buffer, | 18217 size_t bufsize, struct passwd **result); | 18218 18219 DESCRIPTION 18220 The getpwnam( ) function shall search the user database for an entry with a matching name. 18221 The getpwnam( ) function need not be reentrant. A function that is not required to be reentrant is 18222 not required to be thread-safe. 18223 Applications wishing to check for error situations should set errno to 0 before calling | 18224 getpwnam( ). If getpwnam( ) returns a null pointer and errno is non-zero, an error occurred. | 18225 TSF The getpwnam_r( ) function updates the passwd structure pointed to by pwd and stores a pointer | 18226 to that structure at the location pointed to by result. The structure shall contain an entry from 18227 the user database with a matching name. Storage referenced by the structure is allocated from 18228 the memory provided with the buffer parameter, which is bufsize characters in size. | 18229 Notes to Reviewers | 18230 This section with side shading will not appear in the final copy. - Ed. | 18231 D3, XSH, ERN 301 says that the size above is in bytes, not characters, and proposes changing | 18232 "characters" to "bytes". | 18233 The maximum size needed for this buffer can be determined with the | 18234 {_SC_GETPW_R_SIZE_MAX} sysconf( ) parameter. A NULL pointer shall be returned at the 18235 location pointed to by result on error or if the requested entry is not found. | 18236 RETURN VALUE 18237 The getpwnam( ) function shall return a pointer to a struct passwd with the structure as defined 18238 in with a matching entry if found. A null pointer shall be returned if the requested | 18239 entry is not found, or an error occurs. On error, errno shall be set to indicate the error. | 18240 The return value may point to a static area which is overwritten by a subsequent call to 18241 getpwent( ), getpwnam( ), or getpwuid( ). 18242 TSF If successful, the getpwnam_r( ) function shall return zero; otherwise, an error number shall be 18243 returned to indicate the error. 18244 ERRORS 18245 The getpwnam( ) and getpwnam_r( ) functions may fail if: | 18246 [EIO] An I/O error has occurred. | 18247 [EINTR] A signal was caught during getpwnam( ). | 18248 [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. | 18249 [ENFILE] The maximum allowable number of files is currently open in the system. | 18250 TSF The getpwnam_r( ) function may fail if: 18251 TSF [ERANGE] Insufficient storage was supplied via buffer and bufsize to contain the data to | 18252 be referenced by the resulting passwd structure. System Interfaces, Issue 6 1055 getpwnam( ) System Interfaces 18253 EXAMPLES 18254 Getting an Entry for the Login Name 18255 The following example uses the getlogin( ) function to return the name of the user who logged in; 18256 this information is passed to the getpwnam( ) function to get the user database entry for that user. 18257 #include 18258 #include 18259 #include 18260 #include 18261 #include 18262 ... 18263 char *lgn; 18264 struct passwd *pw; 18265 ... 18266 if ((lgn = getlogin()) == NULL || (pw = getpwnam(lgn)) == NULL) { 18267 fprintf(stderr, "Get of user information failed.\n"); exit(1); 18268 } 18269 ... 18270 APPLICATION USAGE 18271 Three names associated with the current process can be determined: getpwuid(geteuid( )) returns 18272 the name associated with the effective user ID of the process; getlogin( ) returns the name 18273 associated with the current login activity; and getpwuid(getuid( )) returns the name associated 18274 with the real user ID of the process. 18275 The getpwnam_r( ) function is thread-safe and shall return values in a user-supplied buffer 18276 instead of possibly using a static data area that may be overwritten by each call. 18277 RATIONALE 18278 None. 18279 FUTURE DIRECTIONS 18280 None. 18281 SEE ALSO 18282 getpwuid( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , , | 18283 18284 CHANGE HISTORY 18285 First released in Issue 1. Derived from System V Release 2.0. | 18286 Issue 4 18287 The DESCRIPTION is clarified. 18288 The header is now marked as optional (OH); this header need not be included on 18289 XSI-conformant systems. 18290 The last sentence in the RETURN VALUE section, indicating that errno is set on error, is marked 18291 as an extension. 18292 The errors [EIO], [EINTR], [EMFILE], and [ENFILE] are marked as extensions. 18293 The APPLICATION USAGE section is expanded to warn about possible reuses of the area used 18294 to pass the return value, and to indicate how applications should check for errors. 18295 The following change is incorporated for alignment with the ISO POSIX-1 standard: 1056 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getpwnam( ) 18296 * The type of argument name is changed from char* to const char*. 18297 Issue 5 18298 Normative text previously in the APPLICATION USAGE section is moved to the RETURN 18299 VALUE section. 18300 The getpwnam_r( ) function is included for alignment with the POSIX Threads Extension. 18301 A note indicating that the getpwnam( ) function need not be reentrant is added to the 18302 DESCRIPTION. 18303 Issue 6 18304 The getpwnam_r( ) function is marked as part of the Thread-Safe Functions option. | 18305 The Open Group corrigenda item U028/3 has been applied correcting text in the DESCRIPTION 18306 describing matching the name. 18307 In the SYNOPSIS, the inclusion of is no longer required. 18308 In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. 18309 The following new requirements on POSIX implementations derive from alignment with the 18310 Single UNIX Specification: 18311 * The requirement to include has been removed. Although was 18312 required for conforming implementations of previous POSIX specifications, it was not 18313 required for UNIX applications. 18314 * In the RETURN VALUE section, the requirement to set errno on error is added. 18315 * The [EMFILE], [ENFILE], and [ENXIO] optional error conditions are added. 18316 The APPLICATION USAGE section is updated to include a note on the thread-safe function and 18317 its avoidance of possibly using a static data area. System Interfaces, Issue 6 1057 getpwuid( ) System Interfaces 18318 NAME 18319 getpwuid, getpwuid_r - search user database for a user ID 18320 SYNOPSIS 18321 #include 18322 struct passwd *getpwuid(uid_t uid); 18323 TSF int getpwuid_r(uid_t uid, struct passwd *pwd, char *buffer, 18324 size_t bufsize, struct passwd **result); 18325 18326 DESCRIPTION 18327 The getpwuid( ) function shall search the user database for an entry with a matching uid. 18328 The getpwuid( ) function need not be reentrant. A function that is not required to be reentrant is 18329 not required to be thread-safe. 18330 Applications wishing to check for error situations should set errno to 0 before calling getpwuid( ). | 18331 If getpwuid( ) returns a null pointer and errno is set to non-zero, an error occurred. | 18332 TSF The getpwuid_r( ) function updates the passwd structure pointed to by pwd and stores a pointer | 18333 to that structure at the location pointed to by result. The structure shall contain an entry from 18334 the user database with a matching uid. Storage referenced by the structure is allocated from the 18335 memory provided with the buffer parameter, which is bufsize characters in size. The maximum 18336 size needed for this buffer can be determined with the {_SC_GETPW_R_SIZE_MAX} sysconf( ) 18337 parameter. A NULL pointer shall be returned at the location pointed to by result on error or if the 18338 requested entry is not found. | 18339 RETURN VALUE 18340 The getpwuid( ) function shall return a pointer to a struct passwd with the structure as defined in 18341 with a matching entry if found. A null pointer shall be returned if the requested entry | 18342 is not found, or an error occurs. On error, errno shall be set to indicate the error. | 18343 The return value may point to a static area which is overwritten by a subsequent call to 18344 getpwent( ), getpwnam( ), or getpwuid( ). 18345 TSF If successful, the getpwuid_r( ) function shall return zero; otherwise, an error number shall be 18346 returned to indicate the error. 18347 ERRORS 18348 The getpwuid( ) and getpwuid_r( ) functions may fail if: | 18349 [EIO] An I/O error has occurred. | 18350 [EINTR] A signal was caught during getpwuid( ). | 18351 [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. | 18352 [ENFILE] The maximum allowable number of files is currently open in the system. | 18353 TSF The getpwuid_r( ) function may fail if: 18354 TSF [ERANGE] Insufficient storage was supplied via buffer and bufsize to contain the data to | 18355 be referenced by the resulting passwd structure. 1058 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getpwuid( ) 18356 EXAMPLES 18357 Getting an Entry for the Root User 18358 The following example gets the user database entry for the user with user ID 0 (root). 18359 #include 18360 #include 18361 ... 18362 uid_t id = 0; 18363 struct passwd *pwd; 18364 pwd = getpwuid(id); 18365 Finding the Name for the Effective User ID 18366 The following example defines pws as a pointer to a structure of type passwd, which is used to 18367 store the structure pointer returned by the call to the getpwuid( ) function. The geteuid( ) function 18368 shall return the effective user ID of the calling process; this is used as the search criteria for the 18369 getpwuid( ) function. The call to getpwuid( ) shall return a pointer to the structure containing that 18370 user ID value. 18371 #include 18372 #include 18373 #include 18374 ... 18375 struct passwd *pws; 18376 pws = getpwuid(geteuid()); 18377 Finding an Entry in the User Database 18378 The following example uses getpwuid( ) to search the user database for a user ID that was 18379 previously stored in a stat structure, then prints out the user name if it is found. If the user is not 18380 found, the program prints the numeric value of the user ID for the entry. 18381 #include 18382 #include 18383 #include 18384 ... 18385 struct stat statbuf; 18386 struct passwd *pwd; 18387 ... 18388 if ((pwd = getpwuid(statbuf.st_uid)) != NULL) 18389 printf(" %-8.8s", pwd->pw_name); 18390 else 18391 printf(" %-8d", statbuf.st_uid); 18392 APPLICATION USAGE 18393 Three names associated with the current process can be determined: getpwuid(geteuid( )) returns 18394 the name associated with the effective user ID of the process; getlogin( ) returns the name 18395 associated with the current login activity; and getpwuid(getuid( )) returns the name associated 18396 with the real user ID of the process. 18397 The getpwuid_r( ) function is thread-safe and shall return values in a user-supplied buffer instead 18398 of possibly using a static data area that may be overwritten by each call. System Interfaces, Issue 6 1059 getpwuid( ) System Interfaces 18399 RATIONALE 18400 None. 18401 FUTURE DIRECTIONS 18402 None. 18403 SEE ALSO 18404 getpwnam( ), geteuid( ), getuid( ), getlogin( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 18405 , , 18406 CHANGE HISTORY 18407 First released in Issue 1. Derived from System V Release 2.0. | 18408 Issue 4 18409 The DESCRIPTION is clarified. 18410 The header is now marked as optional (OH); this header need not be included on 18411 XSI-conformant systems. 18412 The last sentence in the RETURN VALUE section, indicating that errno is set on error, is marked 18413 as an extension. 18414 The errors [EIO], [EINTR], [EMFILE], and [ENFILE] are marked as extensions. 18415 A note is added to the APPLICATION USAGE section indicating how an application should 18416 check for errors. 18417 Issue 5 18418 Normative text previously in the APPLICATION USAGE section is moved to the RETURN 18419 VALUE section. 18420 The getpwuid_r( ) function is included for alignment with the POSIX Threads Extension. 18421 A note indicating that the getpwuid( ) function need not be reentrant is added to the 18422 DESCRIPTION. 18423 Issue 6 18424 The getpwuid_r( ) function is marked as part of the Thread-Safe Functions option. | 18425 The Open Group corrigenda item U028/3 has been applied correcting text in the DESCRIPTION 18426 describing matching the uid. 18427 In the SYNOPSIS, the inclusion of is no longer required. 18428 In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. 18429 The following new requirements on POSIX implementations derive from alignment with the 18430 Single UNIX Specification: 18431 * The requirement to include has been removed. Although was 18432 required for conforming implementations of previous POSIX specifications, it was not 18433 required for UNIX applications. 18434 * In the RETURN VALUE section, the requirement to set errno on error is added. 18435 * The [EIO], [EINTR], [EMFILE], and [ENFILE] optional error conditions are added. 18436 The APPLICATION USAGE section is updated to include a note on the thread-safe function and 18437 its avoidance of possibly using a static data area. 1060 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getrlimit( ) 18438 NAME 18439 getrlimit, setrlimit - control maximum resource consumption 18440 SYNOPSIS 18441 XSI #include 18442 int getrlimit(int resource, struct rlimit *rlp); 18443 int setrlimit(int resource, const struct rlimit *rlp); 18444 18445 DESCRIPTION 18446 Limits on the consumption of a variety of resources by the calling process may be obtained with 18447 getrlimit( ) and set with setrlimit( ). 18448 Each call to either getrlimit( ) or setrlimit( ) identifies a specific resource to be operated upon as 18449 well as a resource limit. A resource limit is represented by an rlimit structure. The rlim_cur 18450 member specifies the current or soft limit and the rlim_max member specifies the maximum or 18451 hard limit. Soft limits may be changed by a process to any value that is less than or equal to the 18452 hard limit. A process may (irreversibly) lower its hard limit to any value that is greater than or 18453 equal to the soft limit. Only a process with appropriate privileges can raise a hard limit. Both 18454 hard and soft limits can be changed in a single call to setrlimit( ) subject to the constraints 18455 described above. 18456 The value RLIM_INFINITY, defined in , shall be considered to be larger than 18457 any other limit value. If a call to getrlimit( ) returns RLIM_INFINITY for a resource, it means the 18458 implementation shall not enforce limits on that resource. Specifying RLIM_INFINITY as any 18459 resource limit value on a successful call to setrlimit( ) inhibits enforcement of that resource limit. 18460 The following resources are defined: 18461 RLIMIT_CORE This is the maximum size of a core file in bytes that may be created by a 18462 process. A limit of 0 shall prevent the creation of a core file. If this limit is 18463 exceeded, the writing of a core file shall terminate at this size. 18464 RLIMIT_CPU This is the maximum amount of CPU time in seconds used by a process. 18465 If this limit is exceeded, SIGXCPU shall be generated for the process. If 18466 the process is catching or ignoring SIGXCPU, or all threads belonging to 18467 that process are blocking SIGXCPU, the behavior is unspecified. 18468 RLIMIT_DATA This is the maximum size of a process' data segment in bytes. If this limit 18469 is exceeded, the malloc( ) function shall fail with errno set to [ENOMEM]. | 18470 RLIMIT_FSIZE This is the maximum size of a file in bytes that may be created by a 18471 process. If a write or truncate operation would cause this limit to be 18472 exceeded, SIGXFSZ shall be generated for the thread. If the thread is 18473 blocking, or the process is catching or ignoring SIGXFSZ, continued 18474 attempts to increase the size of a file from end-of-file to beyond the limit 18475 shall fail with errno set to [EFBIG]. | 18476 RLIMIT_NOFILE This is a number one greater than the maximum value that the system 18477 may assign to a newly-created descriptor. If this limit is exceeded, 18478 functions that allocate new file descriptors may fail with errno set to 18479 [EMFILE]. This limit constrains the number of file descriptors that a | 18480 process may allocate. 18481 RLIMIT_STACK This is the maximum size of a process' stack in bytes. The 18482 implementation does not automatically grow the stack beyond this limit. 18483 If this limit is exceeded, SIGSEGV shall be generated for the thread. If the System Interfaces, Issue 6 1061 getrlimit( ) System Interfaces 18484 thread is blocking SIGSEGV, or the process is ignoring or catching 18485 SIGSEGV and has not made arrangements to use an alternate stack, the 18486 disposition of SIGSEGV shall be set to SIG_DFL before it is generated. 18487 RLIMIT_AS This is the maximum size of a process' total available memory, in bytes. If 18488 this limit is exceeded, the malloc( ) and mmap( ) functions shall fail with 18489 errno set to [ENOMEM]. In addition, the automatic stack growth fails | 18490 with the effects outlined above. 18491 When using the getrlimit( ) function, if a resource limit can be represented correctly in an object 18492 of type rlim_t, then its representation is returned; otherwise, if the value of the resource limit is 18493 equal to that of the corresponding saved hard limit, the value returned shall be 18494 RLIM_SAVED_MAX; otherwise, the value returned shall be RLIM_SAVED_CUR. 18495 When using the setrlimit( ) function, if the requested new limit is RLIM_INFINITY, the new limit 18496 shall be ``no limit''; otherwise, if the requested new limit is RLIM_SAVED_MAX, the new limit 18497 shall be the corresponding saved hard limit; otherwise, if the requested new limit is 18498 RLIM_SAVED_CUR, the new limit shall be the corresponding saved soft limit; otherwise, the 18499 new limit shall be the requested value. In addition, if the corresponding saved limit can be 18500 represented correctly in an object of type rlim_t then it shall be overwritten with the new limit. 18501 The result of setting a limit to RLIM_SAVED_MAX or RLIM_SAVED_CUR is unspecified unless 18502 a previous call to getrlimit( ) returned that value as the soft or hard limit for the corresponding 18503 resource limit. 18504 The determination of whether a limit can be correctly represented in an object of type rlim_t is | 18505 implementation-defined. For example, some implementations permit a limit whose value is | 18506 greater than RLIM_INFINITY and others do not. 18507 The exec family of functions also cause resource limits to be saved. 18508 RETURN VALUE 18509 Upon successful completion, getrlimit( ) and setrlimit( ) shall return 0. Otherwise, these functions 18510 shall return -1 and set errno to indicate the error. 18511 ERRORS 18512 The getrlimit( ) and setrlimit( ) functions shall fail if: 18513 [EINVAL] An invalid resource was specified; or in a setrlimit( ) call, the new rlim_cur | 18514 exceeds the new rlim_max. 18515 [EPERM] The limit specified to setrlimit( ) would have raised the maximum limit value, | 18516 and the calling process does not have appropriate privileges. 18517 The setrlimit( ) function may fail if: 18518 [EINVAL] The limit specified cannot be lowered because current usage is already higher | 18519 than the limit. 18520 EXAMPLES 18521 None. 18522 APPLICATION USAGE 18523 If a process attempts to set the hard limit or soft limit for RLIMIT_NOFILE to less than the value 18524 of {_POSIX_OPEN_MAX} from , unexpected behavior may occur. 1062 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getrlimit( ) 18525 RATIONALE 18526 None. 18527 FUTURE DIRECTIONS 18528 None. 18529 SEE ALSO 18530 exec, fork( ), malloc( ), open( ), sigaltstack( ), sysconf( ), ulimit( ), the Base Definitions volume of | 18531 IEEE Std. 1003.1-200x, , | 18532 CHANGE HISTORY 18533 First released in Issue 4, Version 2. 18534 Issue 5 18535 Moved from X/OPEN UNIX extension to BASE and an APPLICATION USAGE section is added. 18536 Large File Summit extensions are added. System Interfaces, Issue 6 1063 getrusage( ) System Interfaces 18537 NAME 18538 getrusage - get information about resource utilization 18539 SYNOPSIS 18540 XSI #include 18541 int getrusage(int who, struct rusage *r_usage); 18542 18543 DESCRIPTION 18544 The getrusage( ) function provides measures of the resources used by the current process or its 18545 terminated and waited-for child processes. If the value of the who argument is RUSAGE_SELF, 18546 information shall be returned about resources used by the current process. If the value of the who 18547 argument is RUSAGE_CHILDREN, information shall be returned about resources used by the 18548 terminated and waited-for children of the current process. If the child is never waited for (for 18549 example, if the parent has SA_NOCLDWAIT set or sets SIGCHLD to SIG_IGN), the resource 18550 information for the child process is discarded and not included in the resource information 18551 provided by getrusage( ). 18552 The r_usage argument is a pointer to an object of type struct rusage in which the returned 18553 information is stored. 18554 RETURN VALUE 18555 Upon successful completion, getrusage( ) shall return 0; otherwise, -1 shall be returned and errno 18556 set to indicate the error. 18557 ERRORS 18558 The getrusage( ) function shall fail if: 18559 [EINVAL] The value of the who argument is not valid. | 18560 EXAMPLES 18561 Using getrusage( ) 18562 The following example returns information about the resources used by the current process. 18563 #include 18564 ... 18565 int who = RUSAGE_SELF; 18566 struct rusage usage; 18567 int ret; 18568 ret = getrusage(who, &usage); 18569 APPLICATION USAGE 18570 None. 18571 RATIONALE 18572 None. 18573 FUTURE DIRECTIONS 18574 None. 18575 SEE ALSO 18576 exit( ), sigaction( ), time( ), times( ), wait( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 18577 1064 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getrusage( ) 18578 CHANGE HISTORY 18579 First released in Issue 4, Version 2. 18580 Issue 5 18581 Moved from X/OPEN UNIX extension to BASE. System Interfaces, Issue 6 1065 gets( ) System Interfaces 18582 NAME 18583 gets - get a string from a stdin stream 18584 SYNOPSIS 18585 #include 18586 char *gets(char *s); 18587 DESCRIPTION 18588 CX The functionality described on this reference page is aligned with the ISO C standard. Any 18589 conflict between the requirements described here and the ISO C standard is unintentional. This 18590 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 18591 The gets( ) function shall read bytes from the standard input stream, stdin, into the array pointed 18592 to by s, until a newline is read or an end-of-file condition is encountered. Any newline is 18593 discarded and a null byte is placed immediately after the last byte read into the array. 18594 CX The gets( ) function may mark the st_atime field of the file associated with stream for update. The 18595 st_atime field shall be marked for update by the first successful execution of fgetc( ), fgets( ), 18596 fread( ), getc( ), getchar( ), gets( ), fscanf( ), or scanf( ) using stream that returns data not supplied by 18597 a prior call to ungetc( ). 18598 RETURN VALUE 18599 Upon successful completion, gets( ) shall return s. If the stream is at end-of-file, the end-of-file 18600 indicator for the stream shall be set and gets( ) shall return a null pointer. If a read error occurs, 18601 CX the error indicator for the stream shall be set, gets( ) shall return a null pointer and set errno to 18602 indicate the error. 18603 ERRORS 18604 Refer to fgetc( ). 18605 EXAMPLES 18606 None. | 18607 APPLICATION USAGE 18608 Reading a line that overflows the array pointed to by s results in undefined behavior. The use of | 18609 fgets( ) is recommended. | 18610 Since the user cannot specify the length of the buffer passed to gets( ), use of this function is | 18611 discouraged. The length of the string read is unlimited. It is possible to overflow this buffer in | 18612 such a way as to cause applications to fail, or possible system security violations. | 18613 It is recommended that the fgets( ) function should be used to read input lines. | 18614 RATIONALE 18615 None. 18616 FUTURE DIRECTIONS 18617 None. 18618 SEE ALSO 18619 feof( ), ferror( ), fgets( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 18620 CHANGE HISTORY 18621 First released in Issue 1. Derived from Issue 1 of the SVID. | 18622 Issue 4 18623 In the DESCRIPTION: 18624 * The text is changed to make it clear that the function reads bytes rather than (possibly multi- 18625 byte) characters. 1066 Technical Standard (2000) (Draft July 31, 2000) System Interfaces gets( ) 18626 * The list of functions that may cause the st_atime field to be updated is revised. 18627 Issue 6 18628 Extensions beyond the ISO C standard are now marked. System Interfaces, Issue 6 1067 getservbyname( ) System Interfaces 18629 NAME 18630 getservbyname - network services database functions 18631 SYNOPSIS 18632 #include 18633 struct servent *getservbyname(const char *name, const char *proto); 18634 DESCRIPTION 18635 Refer to endservent( ). 1068 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getservbyport( ) 18636 NAME 18637 getservbyport - network services database functions 18638 SYNOPSIS 18639 #include 18640 struct servent *getservbyport(int port, const char *proto); 18641 DESCRIPTION 18642 Refer to endservent( ). System Interfaces, Issue 6 1069 getservent( ) System Interfaces 18643 NAME 18644 getservent - network services database functions 18645 SYNOPSIS 18646 #include 18647 struct servent *getservent(void); 18648 DESCRIPTION 18649 Refer to endservent( ). 1070 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getsid( ) 18650 NAME 18651 getsid - get the process group ID of a session leader 18652 SYNOPSIS 18653 XSI #include 18654 pid_t getsid(pid_t pid); 18655 18656 DESCRIPTION 18657 The getsid( ) function obtains the process group ID of the process that is the session leader of the 18658 process specified by pid. If pid is (pid_t)0, it specifies the calling process. 18659 RETURN VALUE 18660 Upon successful completion, getsid( ) shall return the process group ID of the session leader of 18661 the specified process. Otherwise, it shall return (pid_t)-1 and set errno to indicate the error. 18662 ERRORS 18663 The getsid( ) function shall fail if: 18664 [EPERM] The process specified by pid is not in the same session as the calling process, | 18665 and the implementation does not allow access to the process group ID of the 18666 session leader of that process from the calling process. 18667 [ESRCH] There is no process with a process ID equal to pid. | 18668 EXAMPLES 18669 None. 18670 APPLICATION USAGE 18671 None. 18672 RATIONALE 18673 None. 18674 FUTURE DIRECTIONS 18675 None. 18676 SEE ALSO 18677 exec, fork( ), getpid( ), getpgid( ), setpgid( ), setsid( ), the Base Definitions volume of | 18678 IEEE Std. 1003.1-200x, | 18679 CHANGE HISTORY 18680 First released in Issue 4, Version 2. 18681 Issue 5 18682 Moved from X/OPEN UNIX extension to BASE. System Interfaces, Issue 6 1071 getsockname( ) System Interfaces 18683 NAME 18684 getsockname - get the socket name 18685 SYNOPSIS 18686 #include 18687 int getsockname(int socket, struct sockaddr *restrict address, | 18688 socklen_t *address_len); | 18689 DESCRIPTION 18690 The getsockname( ) function shall retrieve the locally-bound name of the specified socket, store 18691 this address in the sockaddr structure pointed to by the address argument, and store the length of 18692 this address in the object pointed to by the address_len argument. 18693 If the actual length of the address is greater than the length of the supplied sockaddr structure, 18694 the stored address shall be truncated. 18695 If the socket has not been bound to a local name, the value stored in the object pointed to by 18696 address is unspecified. 18697 RETURN VALUE 18698 Upon successful completion, 0 shall be returned, the address argument shall point to the address 18699 of the socket, and the address_len argument shall point to the length of the address. Otherwise, -1 18700 shall be returned and errno set to indicate the error. 18701 ERRORS 18702 The getsockname( ) function shall fail if: 18703 [EBADF] The socket argument is not a valid file descriptor. | 18704 [ENOTSOCK] The socket argument does not refer to a socket. 18705 [EOPNOTSUPP] The operation is not supported for this socket's protocol. 18706 The getsockname( ) function may fail if: 18707 [EINVAL] The socket has been shut down. 18708 [ENOBUFS] Insufficient resources were available in the system to complete the function. | 18709 EXAMPLES 18710 None. 18711 APPLICATION USAGE 18712 None. 18713 RATIONALE 18714 None. 18715 FUTURE DIRECTIONS 18716 None. 18717 SEE ALSO 18718 accept( ), bind( ), getpeername( ), socket( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 18719 18720 CHANGE HISTORY 18721 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. | 18722 The restrict keyword is added to the getsockname( ) prototype for alignment with the | 18723 ISO/IEC 9899: 1999 standard. | 1072 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getsockopt( ) 18724 NAME 18725 getsockopt - get the socket options 18726 SYNOPSIS 18727 #include 18728 int getsockopt(int socket, int level, int option_name, 18729 void *restrict option_value, socklen_t *restrict option_len); | 18730 DESCRIPTION | 18731 The getsockopt( ) function manipulates options associated with a socket. 18732 The getsockopt( ) function shall retrieve the value for the option specified by the option_name 18733 argument for the socket specified by the socket argument. If the size of the option value is greater 18734 than option_len, the value stored in the object pointed to by the option_value argument shall be 18735 silently truncated. Otherwise, the object pointed to by the option_len argument shall be modified 18736 to indicate the actual length of the value. 18737 The level argument specifies the protocol level at which the option resides. To retrieve options at 18738 the socket level, specify the level argument as SOL_SOCKET. To retrieve options at other levels, 18739 supply the appropriate level identifier for the protocol controlling the option. For example, to 18740 indicate that an option is interpreted by the TCP (Transmission Control Protocol), set level to 18741 IPPROTO_TCP as defined in the header. 18742 The socket in use may require the process to have appropriate privileges to use the getsockopt( ) 18743 function. 18744 The option_name argument specifies a single option to be retrieved. It can be one of the following 18745 values defined in : 18746 SO_DEBUG Reports whether debugging information is being recorded. This option 18747 stores an int value. This is a Boolean option. 18748 SO_ACCEPTCONN Reports whether socket listening is enabled. This option stores an int 18749 value. This is a Boolean option. 18750 SO_BROADCAST Reports whether transmission of broadcast messages is supported, if this 18751 is supported by the protocol. This option stores an int value. This is a 18752 Boolean option. 18753 SO_REUSEADDR Reports whether the rules used in validating addresses supplied to bind( ) 18754 should allow reuse of local addresses, if this is supported by the protocol. 18755 This option stores an int value. This is a Boolean option. 18756 SO_KEEPALIVE Reports whether connections are kept active with periodic transmission 18757 of messages, if this is supported by the protocol. 18758 If the connected socket fails to respond to these messages, the connection | 18759 is broken and threads writing to that socket are notified with a SIGPIPE | 18760 signal. This option stores an int value. 18761 This is a Boolean option. 18762 SO_LINGER Reports whether the socket lingers on close( ) if data is present. If 18763 SO_LINGER is set, the system blocks the process during close( ) until it 18764 can transmit the data or until the end of the interval indicated by the 18765 l_linger member, whichever comes first. If SO_LINGER is not specified, 18766 and close( ) is issued, the system handles the call in a way that allows the 18767 process to continue as quickly as possible. This option stores a linger 18768 structure. System Interfaces, Issue 6 1073 getsockopt( ) System Interfaces 18769 SO_OOBINLINE Reports whether the socket leaves received out-of-band data (data 18770 marked urgent) inline. This option stores an int value. This is a Boolean 18771 option. 18772 SO_SNDBUF Reports send buffer size information. This option stores an int value. 18773 SO_RCVBUF Reports receive buffer size information. This option stores an int value. 18774 SO_ERROR Reports information about error status and clears it. This option stores an 18775 int value. 18776 SO_TYPE Reports the socket type. This option stores an int value. 18777 SO_DONTROUTE Reports whether outgoing messages bypass the standard routing 18778 facilities. The destination shall be on a directly-connected network, and 18779 messages are directed to the appropriate network interface according to 18780 the destination address. The effect, if any, of this option depends on what 18781 protocol is in use. This option stores an int value. This is a Boolean 18782 option. 18783 SO_RCVLOWAT Reports the minimum number of bytes to process for socket input 18784 operations. The default value for SO_RCVLOWAT is 1. If 18785 SO_RCVLOWAT is set to a larger value, blocking receive calls normally 18786 wait until they have received the smaller of the low water mark value or 18787 the requested amount. (They may return less than the low water mark if 18788 an error occurs, a signal is caught, or the type of data next in the receive 18789 queue is different than that returned; for example, out-of-band data.) 18790 This option stores an int value. Note that not all implementations allow 18791 this option to be retrieved. 18792 SO_RCVTIMEO Reports the timeout value for input operations. This option stores a 18793 timeval structure with the number of seconds and microseconds 18794 specifying the limit on how long to wait for an input operation to 18795 complete. If a receive operation has blocked for this much time without 18796 receiving additional data, it shall return with a partial count or errno set to 18797 [EAGAIN] or [EWOULDBLOCK] if no data was received. The default for 18798 this option is zero, which indicates that a receive operation shall not time 18799 out. Note that not all implementations allow this option to be retrieved. 18800 SO_SNDLOWAT Reports the minimum number of bytes to process for socket output 18801 operations. Non-blocking output operations shall process no data if flow 18802 control does not allow the smaller of the send low water mark value or 18803 the entire request to be processed. This option stores an int value. Note 18804 that not all implementations allow this option to be retrieved. 18805 SO_SNDTIMEO Reports the timeout value specifying the amount of time that an output 18806 function blocks because flow control prevents data from being sent. If a 18807 send operation has blocked for this time, it shall return with a partial 18808 count or with errno set to [EAGAIN] or [EWOULDBLOCK] if no data 18809 were sent. The default for this option is zero, which indicates that a send 18810 operation shall not time out. The option stores a timeval structure. Note 18811 that not all implementations allow this option to be retrieved. 18812 For Boolean options, a zero value indicates that the option is disabled and a non-zero value 18813 indicates that the option is enabled. 18814 Options at other protocol levels vary in format and name. 1074 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getsockopt( ) 18815 The socket in use may require the process to have appropriate privileges to use the getsockopt( ) 18816 function. 18817 RETURN VALUE 18818 Upon successful completion, getsockopt( ) shall return 0; otherwise, -1 shall be returned and errno 18819 set to indicate the error. 18820 ERRORS 18821 The getsockopt( ) function shall fail if: 18822 [EBADF] The socket argument is not a valid file descriptor. | 18823 [EINVAL] The specified option is invalid at the specified socket level. 18824 [ENOPROTOOPT] 18825 The option is not supported by the protocol. 18826 [ENOTSOCK] The socket argument does not refer to a socket. 18827 The getsockopt( ) function may fail if: 18828 [EACCES] The calling process does not have the appropriate privileges. 18829 [EINVAL] The socket has been shut down. 18830 [ENOBUFS] Insufficient resources are available in the system to complete the function. | 18831 EXAMPLES 18832 None. 18833 APPLICATION USAGE 18834 None. 18835 RATIONALE 18836 None. 18837 FUTURE DIRECTIONS 18838 None. 18839 SEE ALSO 18840 bind( ), close( ), endprotoent( ), setsockopt( ), socket( ), the Base Definitions volume of | 18841 IEEE Std. 1003.1-200x, , | 18842 CHANGE HISTORY 18843 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. | 18844 The restrict keyword is added to the getsockopt( ) prototype for alignment with the | 18845 ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 1075 getsubopt( ) System Interfaces 18846 NAME 18847 getsubopt - parse suboption arguments from a string 18848 SYNOPSIS 18849 XSI #include 18850 int getsubopt(char **optionp, char * const *tokens, char **valuep); 18851 18852 DESCRIPTION 18853 The getsubopt( ) function parses suboption arguments in a flag argument that was initially parsed 18854 by getopt( ). The application shall ensure that these suboption arguments are separated by 18855 commas and may consist of either a single token, or a token-value pair separated by an equal 18856 sign. Because commas delimit suboption arguments in the option string, they are not allowed to 18857 be part of the suboption arguments or the value of a suboption argument. Similarly, because the | 18858 equal sign separates a token from its value, undefined behavior will result if the application | 18859 passes a token that contains an equal sign. | 18860 The getsubopt( ) function takes the address of a pointer to the option argument string, a vector of 18861 possible tokens, and the address of a value string pointer. If the option argument string at 18862 *optionp contains only one suboption argument, getsubopt( ) updates *optionp to point to the null 18863 at the end of the string. Otherwise, it isolates the suboption argument by replacing the comma 18864 separator with a null, and updates *optionp to point to the start of the next suboption argument. 18865 If the suboption argument has an associated value, getsubopt( ) updates *valuep to point to the 18866 value's first character. Otherwise, it sets *valuep to a null pointer. 18867 The token vector is organized as a series of pointers to strings. The end of the token vector is 18868 identified by a null pointer. 18869 When getsubopt( ) returns, if *valuep is not a null pointer, then the suboption argument processed 18870 included a value. The calling program may use this information to determine whether the 18871 presence or lack of a value for this suboption is an error. 18872 Additionally, when getsubopt( ) fails to match the suboption argument with the tokens in the 18873 tokens array, the calling program should decide if this is an error, or if the unrecognized option 18874 should be passed on to another program. 18875 RETURN VALUE 18876 The getsubopt( ) function shall return the index of the matched token string, or -1 if no token 18877 strings were matched. 18878 ERRORS 18879 No errors are defined. 18880 EXAMPLES 18881 #include 18882 #include 18883 int do_all; 18884 const char *type; 18885 int read_size; 18886 int write_size; 18887 int read_only; 18888 enum 18889 { 18890 RO_OPTION = 0, 18891 RW_OPTION, 1076 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getsubopt( ) 18892 READ_SIZE_OPTION, 18893 WRITE_SIZE_OPTION 18894 }; 18895 const char *mount_opts[] = 18896 { 18897 [RO_OPTION] = "ro", 18898 [RW_OPTION] = "rw", 18899 [READ_SIZE_OPTION] = "rsize", 18900 [WRITE_SIZE_OPTION] = "wsize", 18901 NULL 18902 }; 18903 int 18904 main(int argc, char *argv[]) 18905 { 18906 char *subopts, *value; 18907 int opt; 18908 while ((opt = getopt(argc, argv, "at:o:")) != -1) 18909 switch(opt) 18910 { 18911 case 'a': 18912 do_all = 1; 18913 break; 18914 case 't': 18915 type = optarg; 18916 break; 18917 case 'o': 18918 subopts = optarg; 18919 while (*subopts != ' ') 18920 switch(getsubopt(&subopts, mount_opts, &value)) 18921 { 18922 case RO_OPTION: 18923 read_only = 1; 18924 break; 18925 case RW_OPTION: 18926 read_only = 0; 18927 break; 18928 case READ_SIZE_OPTION: 18929 if (value == NULL) 18930 abort(); 18931 read_size = atoi(value); 18932 break; 18933 case WRITE_SIZE_OPTION: 18934 if (value == NULL) 18935 abort(); 18936 write_size = atoi(value); 18937 break; 18938 default: 18939 /* Unknown suboption. */ 18940 printf("Unknown suboption `%s'0, value); 18941 break; 18942 } System Interfaces, Issue 6 1077 getsubopt( ) System Interfaces 18943 break; 18944 default: 18945 abort(); 18946 } 18947 /* Do the real work. */ 18948 return 0; 18949 } 18950 Parsing Suboptions 18951 The following example uses the getsubopt( ) function to parse a value argument in the optarg 18952 external variable returned by a call to getopt( ). 18953 #include 18954 ... 18955 char *tokens[] = {"HOME", "PATH", "LOGNAME", (char *) NULL }; 18956 char *value; 18957 int opt, index; 18958 while ((opt = getopt(argc, argv, "e:")) != -1) { 18959 switch(opt) { 18960 case 'e' : 18961 while ((index = getsubopt(&optarg, tokens, &value)) != -1) { 18962 switch(index) { 18963 ... 18964 } 18965 break; 18966 ... 18967 } 18968 } 18969 ... 18970 APPLICATION USAGE 18971 None. 18972 RATIONALE 18973 None. 18974 FUTURE DIRECTIONS 18975 None. 18976 SEE ALSO 18977 getopt( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 18978 CHANGE HISTORY 18979 First released in Issue 4, Version 2. 18980 Issue 5 18981 Moved from X/OPEN UNIX extension to BASE. 1078 Technical Standard (2000) (Draft July 31, 2000) System Interfaces gettimeofday( ) 18982 NAME 18983 gettimeofday - get the date and time 18984 SYNOPSIS 18985 XSI #include 18986 int gettimeofday(struct timeval *restrict tp, void *tzp); | 18987 | 18988 DESCRIPTION 18989 The gettimeofday( ) function obtains the current time, expressed as seconds and microseconds 18990 since the Epoch, and stores it in the timeval structure pointed to by tp. The resolution of the 18991 system clock is unspecified. 18992 If tzp is not a null pointer, the behavior is unspecified. 18993 RETURN VALUE 18994 The gettimeofday( ) function shall return 0 and no value shall be reserved to indicate an error. 18995 ERRORS 18996 No errors are defined. 18997 EXAMPLES 18998 None. 18999 APPLICATION USAGE 19000 None. 19001 RATIONALE 19002 None. 19003 FUTURE DIRECTIONS 19004 None. 19005 SEE ALSO 19006 ctime( ), ftime( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 19007 CHANGE HISTORY 19008 First released in Issue 4, Version 2. 19009 Issue 5 19010 Moved from X/OPEN UNIX extension to BASE. 19011 Issue 6 19012 The DESCRIPTION is updated to refer to ``seconds since the Epoch'' rather than ``seconds since 19013 00:00:00 UTC (Coordinated Universal Time), January 1 1970'' for consistency with other time | 19014 functions. System Interfaces, Issue 6 1079 getuid( ) System Interfaces 19015 NAME 19016 getuid - get a real user ID 19017 SYNOPSIS 19018 #include 19019 uid_t getuid(void); | 19020 DESCRIPTION | 19021 The getuid( ) function shall return the real user ID of the calling process. 19022 RETURN VALUE 19023 The getuid( ) function is always successful and no return value is reserved to indicate the error. 19024 ERRORS 19025 No errors are defined. 19026 EXAMPLES 19027 Setting the Effective User ID to the Real User ID 19028 The following example sets the effective user ID and the real user ID of the current process to the 19029 real user ID of the caller. 19030 #include 19031 #include 19032 ... 19033 setreuid(getuid(), getuid()); 19034 ... 19035 APPLICATION USAGE 19036 None. 19037 RATIONALE 19038 None. 19039 FUTURE DIRECTIONS 19040 None. 19041 SEE ALSO 19042 getegid( ), geteuid( ), getgid( ), setegid( ), seteuid( ), setgid( ), setregid( ), setreuid( ), setuid( ), the Base | 19043 Definitions volume of IEEE Std. 1003.1-200x, , | 19044 CHANGE HISTORY 19045 First released in Issue 1. Derived from Issue 1 of the SVID. | 19046 Issue 4 19047 The header is now marked as optional (OH); this header need not be included on 19048 XSI-conformant systems. 19049 The header is added to the SYNOPSIS section. 19050 The following change is incorporated for alignment with the ISO POSIX-1 standard: 19051 * The argument list is explicitly defined as void. 19052 Issue 6 19053 In the SYNOPSIS, the inclusion of is no longer required. 19054 The following new requirements on POSIX implementations derive from alignment with the 19055 Single UNIX Specification: 1080 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getuid( ) 19056 * The requirement to include has been removed. Although was 19057 required for conforming implementations of previous POSIX specifications, it was not 19058 required for UNIX applications. System Interfaces, Issue 6 1081 getutxent( ) System Interfaces 19059 NAME 19060 getutxent, getutxid, getutxline - get user accounting database entries 19061 SYNOPSIS 19062 XSI #include 19063 struct utmpx *getutxent(void); 19064 struct utmpx *getutxid(const struct utmpx *id); 19065 struct utmpx *getutxline(const struct utmpx *line); 19066 19067 DESCRIPTION 19068 Refer to endutxent( ). 1082 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getwc( ) 19069 NAME 19070 getwc - get a wide character from a stream 19071 SYNOPSIS 19072 #include 19073 #include 19074 wint_t getwc(FILE *stream); 19075 DESCRIPTION 19076 CX The functionality described on this reference page is aligned with the ISO C standard. Any 19077 conflict between the requirements described here and the ISO C standard is unintentional. This 19078 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 19079 The getwc( ) function is equivalent to fgetwc( ), except that if it is implemented as a macro it may 19080 evaluate stream more than once, so the argument should never be an expression with side effects. 19081 RETURN VALUE 19082 Refer to fgetwc( ). 19083 ERRORS 19084 Refer to fgetwc( ). 19085 EXAMPLES 19086 None. 19087 APPLICATION USAGE 19088 Because it may be implemented as a macro, getwc( ) may treat incorrectly a stream argument with 19089 side effects. In particular, getwc(*f++) does not necessarily work as expected. Therefore, use of 19090 this function is not recommended; fgetwc( ) should be used instead. 19091 RATIONALE 19092 None. 19093 FUTURE DIRECTIONS 19094 None. 19095 SEE ALSO 19096 fgetwc( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , | 19097 CHANGE HISTORY 19098 First released as a World-wide Portability Interface in Issue 4. Derived from the MSE working | 19099 draft. 19100 Issue 5 19101 The Optional Header (OH) marking is removed from . System Interfaces, Issue 6 1083 getwchar( ) System Interfaces 19102 NAME 19103 getwchar - get a wide character from a stdin stream 19104 SYNOPSIS 19105 #include 19106 wint_t getwchar(void); 19107 DESCRIPTION 19108 CX The functionality described on this reference page is aligned with the ISO C standard. Any 19109 conflict between the requirements described here and the ISO C standard is unintentional. This 19110 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 19111 The getwchar( ) function is equivalent to getwc(stdin). 19112 RETURN VALUE 19113 Refer to fgetwc( ). 19114 ERRORS 19115 Refer to fgetwc( ). 19116 EXAMPLES 19117 None. 19118 APPLICATION USAGE 19119 If the wint_t value returned by getwchar( ) is stored into a variable of type wchar_t and then 19120 compared against the wint_t macro WEOF, the result may be incorrect. Only the wint_t type is | 19121 guaranteed to be able to represent any wide character and WEOF. | 19122 RATIONALE 19123 None. 19124 FUTURE DIRECTIONS 19125 None. 19126 SEE ALSO 19127 fgetwc( ), getwc( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 19128 CHANGE HISTORY 19129 First released as a World-wide Portability Interface in Issue 4. Derived from the MSE working | 19130 draft. 1084 Technical Standard (2000) (Draft July 31, 2000) System Interfaces getwd( ) 19131 NAME 19132 getwd - get the current working directory path name (LEGACY) 19133 SYNOPSIS 19134 XSI #include 19135 char *getwd(char *path_name); 19136 19137 DESCRIPTION 19138 The getwd( ) function determines an absolute path name of the current working directory of the 19139 calling process, and copies that path name into the array pointed to by the path_name argument. 19140 If the length of the path name of the current working directory is greater than ({PATH_MAX}+1) 19141 including the null byte, getwd( ) shall fail and return a null pointer. 19142 RETURN VALUE 19143 Upon successful completion, a pointer to the string containing the absolute path name of the 19144 current working directory shall be returned. Otherwise, getwd( ) shall return a null pointer and 19145 the contents of the array pointed to by path_name are undefined. 19146 ERRORS 19147 No errors are defined. 19148 EXAMPLES 19149 None. 19150 APPLICATION USAGE 19151 For applications portability, the getcwd( ) function should be used to determine the current 19152 working directory instead of getwd( ). 19153 RATIONALE 19154 Since the user cannot specifyy the length of the buffer passed to getwd( ), use of this function is | 19155 discouraged. The length of a path name described in {PATH_MAX} is file system-dependent and | 19156 may vary from one mount point to another, or might even be unlimited. It is possible to | 19157 overflow this buffer in such a way as to cause applications to fail, or possible system security | 19158 violations. | 19159 It is recommended that the getcwd( ) function should be used to determine the current working | 19160 directory. | 19161 FUTURE DIRECTIONS 19162 This function may be withdrawn in a future version. 19163 SEE ALSO 19164 getcwd( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 19165 CHANGE HISTORY 19166 First released in Issue 4, Version 2. 19167 Issue 5 19168 Moved from X/OPEN UNIX extension to BASE. 19169 Issue 6 19170 This function is marked LEGACY. System Interfaces, Issue 6 1085 glob( ) System Interfaces 19171 NAME 19172 glob, globfree - generate path names matching a pattern | 19173 SYNOPSIS 19174 #include 19175 int glob(const char *restrict pattern, int flags, | 19176 int(*retrict errfunc)(const char *retrict epath, int eerrno), | 19177 glob_t *restrict pglob); | 19178 void globfree(glob_t *pglob); | 19179 DESCRIPTION 19180 The glob( ) function is a path name generator that implements the rules defined in the Shell and | 19181 Utilities volume of IEEE Std. 1003.1-200x, Section 2.14, Pattern Matching Notation, with optional | 19182 support for rule 3 in the Shell and Utilities volume of IEEE Std. 1003.1-200x, Section 2.14.3, | 19183 Patterns Used for File Name Expansion. | 19184 The structure type glob_t is defined in and includes at least the following members: 19185 _________________________________________________________________________ 19186 _ Member Type Member Name Description ________________________________________________________________________ 19187 size_t gl_pathc Count of paths matched by pattern. 19188 char ** gl_pathv Pointer to a list of matched path names. 19189 _ size_t gl_offs Slots to reserve at the beginning of gl_pathv. ________________________________________________________________________ 19190 The argument pattern is a pointer to a path name pattern to be expanded. The glob( ) function 19191 matches all accessible path names against this pattern and develops a list of all path names that 19192 match. In order to have access to a path name, glob( ) requires search permission on every 19193 component of a path except the last, and read permission on each directory of any file name 19194 component of pattern that contains any of the following special characters: '*', '?', and '['. 19195 The glob( ) function stores the number of matched path names into pglob->gl_pathc and a pointer | 19196 to a list of pointers to path names into pglob->gl_pathv. The path names are in sort order as | 19197 defined by the current setting of the LC_COLLATE category; see the Base Definitions volume of | 19198 IEEE Std. 1003.1-200x, Section 7.3.2, LC_COLLATE . The first pointer after the last path name is a | 19199 null pointer. If the pattern does not match any path names, the returned number of matched 19200 paths is set to 0, and the contents of pglob->gl_pathv are implementation-defined. | 19201 It is the caller's responsibility to create the structure pointed to by pglob. The glob( ) function 19202 allocates other space as needed, including the memory pointed to by gl_pathv. The globfree( ) 19203 function frees any space associated with pglob from a previous call to glob( ). 19204 The flags argument is used to control the behavior of glob( ). The value of flags is a bitwise- 19205 inclusive OR of zero or more of the following constants, which are defined in : 19206 GLOB_APPEND Append path names generated to the ones from a previous call to glob( ). 19207 GLOB_DOOFFS Make use of pglob->gl_offs. If this flag is set, pglob->gl_offs is used to | 19208 specify how many null pointers to add to the beginning of pglob- | 19209 >gl_pathv. In other words, pglob->gl_pathv shall point to pglob->gl_offs null | 19210 pointers, followed by pglob->gl_pathc path name pointers, followed by a | 19211 null pointer. | 19212 GLOB_ERR Causes glob( ) to return when it encounters a directory that it cannot open 19213 or read. Ordinarily, glob( ) continues to find matches. 19214 GLOB_MARK Each path name that is a directory that matches pattern has a slash 19215 appended. 1086 Technical Standard (2000) (Draft July 31, 2000) System Interfaces glob( ) 19216 GLOB_NOCHECK Supports rule 3 in the Shell and Utilities volume of IEEE Std. 1003.1-200x, | 19217 Section 2.14.3, Patterns Used for File Name Expansion. If pattern does not | 19218 match any path name, then glob( ) shall return a list consisting of only 19219 pattern, and the number of matched path names is 1. 19220 GLOB_NOESCAPE Disable backslash escaping. 19221 GLOB_NOSORT Ordinarily, glob( ) sorts the matching path names according to the current 19222 setting of the LC_COLLATE category, see the Base Definitions volume of | 19223 IEEE Std. 1003.1-200x, Section 7.3.2, LC_COLLATE . When this flag is | 19224 used, the order of path names returned is unspecified. | 19225 The GLOB_APPEND flag can be used to append a new set of path names to those found in a 19226 previous call to glob( ). The following rules apply to applications when two or more calls to 19227 glob( ) are made with the same value of pglob and without intervening calls to globfree( ): 19228 1. The first such call shall not set GLOB_APPEND. All subsequent calls shall set it. 19229 2. All the calls shall set GLOB_DOOFFS, or all shall not set it. 19230 3. After the second call, pglob->gl_pathv points to a list containing the following: | 19231 a. Zero or more null pointers, as specified by GLOB_DOOFFS and pglob->gl_offs. | 19232 b. Pointers to the path names that were in the pglob->gl_pathv list before the call, in the | 19233 same order as before. | 19234 c. Pointers to the new path names generated by the second call, in the specified order. 19235 4. The count returned in pglob->gl_pathc shall be the total number of path names from the | 19236 two calls. 19237 5. The application can change any of the fields after a call to glob( ). If it does, the application 19238 shall reset them to the original value before a subsequent call, using the same pglob value, 19239 to globfree( ) or glob( ) with the GLOB_APPEND flag. 19240 If, during the search, a directory is encountered that cannot be opened or read and errfunc is not 19241 a null pointer, glob( ) calls (*errfunc( )) with two arguments: 19242 1. The epath argument is a pointer to the path that failed. 19243 2. The eerrno argument is the value of errno from the failure, as set by opendir( ), readdir( ), or 19244 stat( ). (Other values may be used to report other errors not explicitly documented for 19245 those functions.) 19246 The following constants are defined as error return values for glob( ): 19247 GLOB_ABORTED The scan was stopped because GLOB_ERR was set or (*errfunc( )) 19248 returned non-zero. 19249 GLOB_NOMATCH The pattern does not match any existing path name, and 19250 GLOB_NOCHECK was not set in flags. 19251 GLOB_NOSPACE An attempt to allocate memory failed. 19252 If (*errfunc( )) is called and returns non-zero, or if the GLOB_ERR flag is set in flags, glob( ) shall 19253 stop the scan and return GLOB_ABORTED after setting gl_pathc and gl_pathv in pglob to reflect 19254 the paths already scanned. If GLOB_ERR is not set and either errfunc is a null pointer or 19255 (*errfunc( )) returns 0, the error shall be ignored. System Interfaces, Issue 6 1087 glob( ) System Interfaces 19256 RETURN VALUE 19257 Upon successful completion, glob( ) shall return 0. The argument pglob->gl_pathc shall return the | 19258 number of matched path names and the argument pglob->gl_pathv shall contain a pointer to a | 19259 null-terminated list of matched and sorted path names. However, if pglob->gl_pathc is 0, the | 19260 content of pglob->gl_pathv is undefined. | 19261 The globfree( ) function shall return no value. 19262 If glob( ) terminates due to an error, it shall return one of the non-zero constants defined in 19263 . The arguments pglob->gl_pathc and pglob->gl_pathv are still set as defined above. | 19264 ERRORS 19265 No errors are defined. 19266 EXAMPLES 19267 One use of the GLOB_DOOFFS flag is by applications that build an argument list for use with 19268 execv( ), execve( ), or execvp( ). Suppose, for example, that an application wants to do the 19269 equivalent of: 19270 ls -l *.c 19271 but for some reason: 19272 system("ls -l *.c") 19273 is not acceptable. The application could obtain approximately the same result using the 19274 sequence: 19275 globbuf.gl_offs = 2; 19276 glob("*.c", GLOB_DOOFFS, NULL, &globbuf); 19277 globbuf.gl_pathv[0] = "ls"; 19278 globbuf.gl_pathv[1] = "-l"; 19279 execvp("ls", &globbuf.gl_pathv[0]); 19280 Using the same example: 19281 ls -l *.c *.h 19282 could be approximately simulated using GLOB_APPEND as follows: 19283 globbuf.gl_offs = 2; 19284 glob("*.c", GLOB_DOOFFS, NULL, &globbuf); 19285 glob("*.h", GLOB_DOOFFS|GLOB_APPEND, NULL, &globbuf); 19286 ... 19287 APPLICATION USAGE 19288 This function is not provided for the purpose of enabling utilities to perform path name 19289 expansion on their arguments, as this operation is performed by the shell, and utilities are 19290 explicitly not expected to redo this. Instead, it is provided for applications that need to do path 19291 name expansion on strings obtained from other sources, such as a pattern typed by a user or 19292 read from a file. 19293 If a utility needs to see if a path name matches a given pattern, it can use fnmatch( ). 19294 Note that gl_pathc and gl_pathv have meaning even if glob( ) fails. This allows glob( ) to report 19295 partial results in the event of an error. However, if gl_pathc is 0, gl_pathv is unspecified even if 19296 glob( ) did not return an error. 19297 The GLOB_NOCHECK option could be used when an application wants to expand a path name 19298 if wildcards are specified, but wants to treat the pattern as just a string otherwise. The sh utility 19299 might use this for option-arguments, for example. 1088 Technical Standard (2000) (Draft July 31, 2000) System Interfaces glob( ) 19300 The new path names generated by a subsequent call with GLOB_APPEND are not sorted 19301 together with the previous path names. This mirrors the way that the shell handles path name 19302 expansion when multiple expansions are done on a command line. 19303 Applications that need tilde and parameter expansion should use wordexp( ). 19304 RATIONALE 19305 It was claimed that the GLOB_DOOFFS flag is unnecessary because it could be simulated using: 19306 new = (char **)malloc((n + pglob->gl_pathc + 1) 19307 * sizeof(char *)); 19308 (void) memcpy(new+n, pglob->gl_pathv, 19309 pglob->gl_pathc * sizeof(char *)); 19310 (void) memset(new, 0, n * sizeof(char *)); 19311 free(pglob->gl_pathv); 19312 pglob->gl_pathv = new; 19313 However, this assumes that the memory pointed to by gl_pathv is a block that was separately 19314 created using malloc( ). This is not necessarily the case. An application should make no 19315 assumptions about how the memory referenced by fields in pglob was allocated. It might have 19316 been obtained from malloc( ) in a large chunk and then carved up within glob( ), or it might have 19317 been created using a different memory allocator. It is not the intent of the standard developers to 19318 specify or imply how the memory used by glob( ) is managed. 19319 The GLOB_APPEND flag would be used when an application wants to expand several different 19320 patterns into a single list. 19321 FUTURE DIRECTIONS 19322 None. 19323 SEE ALSO 19324 exec, fnmatch( ), opendir( ), readdir( ), stat( ), wordexp( ), the Base Definitions volume of | 19325 IEEE Std. 1003.1-200x, , the Shell and Utilities volume of IEEE Std. 1003.1-200x | 19326 CHANGE HISTORY 19327 First released in Issue 4. Derived from the ISO POSIX-2 standard. | 19328 Issue 5 19329 Moved from POSIX2 C-language Binding to BASE. 19330 Issue 6 19331 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. | 19332 The restrict keyword is added to the glob( ) prototype for alignment with the ISO/IEC 9899: 1999 | 19333 standard. | System Interfaces, Issue 6 1089 gmtime( ) System Interfaces 19334 NAME 19335 gmtime, gmtime_r - convert a time value to a broken-down UTC time 19336 SYNOPSIS 19337 #include 19338 struct tm *gmtime(const time_t *timer); 19339 TSF struct tm *gmtime_r(const time_t *restrict timer, struct tm *restrict result);| 19340 | 19341 DESCRIPTION 19342 CX For gmtime( ): The functionality described on this reference page is aligned with the ISO C 19343 standard. Any conflict between the requirements described here and the ISO C standard is 19344 unintentional. This volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 19345 The gmtime( ) function shall convert the time in seconds since the Epoch pointed to by timer into 19346 a broken-down time, expressed as Coordinated Universal Time (UTC). 19347 CX The gmtime( ) funtion need not be reentrant. A function that is not required to be reentrant is not 19348 required to be thread-safe. 19349 TSF The gmtime_r( ) function shall convert the time in seconds since the Epoch pointed to by timer | 19350 into a broken-down time expressed as Coordinated Universal Time (UTC). The broken-down 19351 time is stored in the structure referred to by result. The gmtime_r( ) function shall also return the 19352 address of the same structure. 19353 RETURN VALUE 19354 The gmtime( ) function shall return a pointer to a struct tm. 19355 TSF Upon successful completion, gmtime_r( ) shall return the address of the structure pointed to by 19356 the argument result. If an error is detected, or UTC is not available, gmtime_r( ) shall return a null 19357 pointer. 19358 ERRORS 19359 No errors are defined. 19360 EXAMPLES 19361 None. 19362 APPLICATION USAGE 19363 The asctime( ), ctime( ), gmtime( ), and localtime( ) functions return values in one of two static 19364 objects: a broken-down time structure and an array of char. Execution of any of the functions 19365 may overwrite the information returned in either of these objects by any of the other functions. 19366 The gmtime_r( ) function is thread-safe and shall return values in a user-supplied buffer instead 19367 of possibly using a static data area that may be overwritten by each call. 19368 RATIONALE 19369 None. 19370 FUTURE DIRECTIONS 19371 None. 19372 SEE ALSO 19373 asctime( ), clock( ), ctime( ), difftime( ), localtime( ), mktime( ), strftime( ), strptime( ), time( ), utime( ), | 19374 the Base Definitions volume of IEEE Std. 1003.1-200x, | 1090 Technical Standard (2000) (Draft July 31, 2000) System Interfaces gmtime( ) 19375 CHANGE HISTORY 19376 First released in Issue 1. Derived from Issue 1 of the SVID. | 19377 Issue 4 19378 In the APPLICATION USAGE section, the list of functions with which this function may interact 19379 is revised and the wording clarified. 19380 The following change is incorporated for alignment with the ISO C standard: 19381 * The type of argument timer is changed from time_t* to const time_t*. 19382 Issue 5 19383 A note indicating that the gmtime( ) function need not be reentrant is added to the 19384 DESCRIPTION. 19385 The gmtime_r( ) function is included for alignment with the POSIX Threads Extension. 19386 Issue 6 19387 The gmtime_r( ) function is marked as part of the Thread-Safe Functions option. | 19388 Extensions beyond the ISO C standard are now marked. 19389 The APPLICATION USAGE section is updated to include a note on the thread-safe function and 19390 its avoidance of possibly using a static data area. | 19391 The restrict keyword is added to the gmtime_r( ) prototype for alignment with the | 19392 ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 1091 grantpt( ) System Interfaces 19393 NAME 19394 grantpt - grant access to the slave pseudo-terminal device 19395 SYNOPSIS 19396 XSI #include 19397 int grantpt(int fildes); 19398 19399 DESCRIPTION 19400 The grantpt( ) function shall change the mode and ownership of the slave pseudo-terminal 19401 device associated with its master pseudo-terminal counterpart. The fildes argument is a file 19402 descriptor that refers to a master pseudo-terminal device. The user ID of the slave shall be set to 19403 the real UID of the calling process and the group ID shall be set to an unspecified group ID. The 19404 permission mode of the slave pseudo-terminal shall be set to readable and writable by the 19405 owner, and writable by the group. 19406 The behavior of the grantpt( ) function is unspecified if the application has installed a signal 19407 handler to catch SIGCHLD signals. 19408 RETURN VALUE 19409 Upon successful completion, grantpt( ) shall return 0; otherwise, it shall return -1 and set errno to 19410 indicate the error. 19411 ERRORS 19412 The grantpt( ) function may fail if: 19413 [EBADF] The fildes argument is not a valid open file descriptor. | 19414 [EINVAL] The fildes argument is not associated with a master pseudo-terminal device. | 19415 [EACCES] The corresponding slave pseudo-terminal device could not be accessed. | 19416 EXAMPLES 19417 None. 19418 APPLICATION USAGE 19419 None. 19420 RATIONALE 19421 None. 19422 FUTURE DIRECTIONS 19423 None. 19424 SEE ALSO 19425 open( ), ptsname( ), unlockpt( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 19426 CHANGE HISTORY 19427 First released in Issue 4, Version 2. 19428 Issue 5 19429 Moved from X/OPEN UNIX extension to BASE. 19430 The last paragraph of the DESCRIPTION is moved from the APPLICATION USAGE section in 19431 previous issues. 1092 Technical Standard (2000) (Draft July 31, 2000) System Interfaces h_errno 19432 NAME 19433 h_errno - error return value for network database operations (LEGACY) 19434 SYNOPSIS 19435 #include 19436 DESCRIPTION 19437 Note that this method of returning errors is used only in connection with legacy functions. 19438 The header provides a declaration of h_errno as a modifiable l-value of type int. 19439 It is unspecified whether h_errno is a macro or an identifier declared with external linkage. If a 19440 macro definition is suppressed in order to access an actual object, or a program defines an 19441 identifier with the name h_errno, the behavior is undefined. 19442 RETURN VALUE 19443 None. 19444 ERRORS 19445 No errors are defined. 19446 EXAMPLES 19447 None. 19448 APPLICATION USAGE 19449 Applications should obtain the definition of h_errno by the inclusion of the header. 19450 The practice of defining h_errno in a program as an extern int h_errno is obsolescent. 19451 RATIONALE 19452 None. 19453 FUTURE DIRECTIONS 19454 h_errno may be withdrawn in a future version. 19455 SEE ALSO 19456 endhostent( ), errno, the Base Definitions volume of IEEE Std. 1003.1-200x, | 19457 CHANGE HISTORY 19458 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. | System Interfaces, Issue 6 1093 hcreate( ) System Interfaces 19459 NAME 19460 hcreate, hdestroy, hsearch - manage hash search table 19461 SYNOPSIS 19462 XSI #include 19463 int hcreate(size_t nel); 19464 void hdestroy(void); 19465 ENTRY *hsearch(ENTRY item, ACTION action); | 19466 | 19467 DESCRIPTION 19468 The hcreate( ), hdestroy( ), and hsearch( ) functions manage hash search tables. 19469 The hcreate( ) function allocates sufficient space for the table, and the application shall ensure it is 19470 called before hsearch( ) is used. The nel argument is an estimate of the maximum number of 19471 entries that the table shall contain. This number may be adjusted upward by the algorithm in 19472 order to obtain certain mathematically favorable circumstances. 19473 The hdestroy( ) function disposes of the search table, and may be followed by another call to 19474 hcreate( ). After the call to hdestroy( ), the data can no longer be considered accessible. 19475 The hsearch( ) function is a hash-table search routine. It shall return a pointer into a hash table 19476 indicating the location at which an entry can be found. The item argument is a structure of type 19477 ENTRY (defined in the header) containing two pointers: item.key points to the 19478 comparison key (a char*), and item.data (a void*) points to any other data to be associated with 19479 that key. The comparison function used by hsearch( ) is strcmp( ). The action argument is a 19480 member of an enumeration type ACTION indicating the disposition of the entry if it cannot be 19481 found in the table. ENTER indicates that the item should be inserted in the table at an 19482 appropriate point. FIND indicates that no entry should be made. Unsuccessful resolution is 19483 indicated by the return of a null pointer. 19484 These functions need not be reentrant. A function that is not required to be reentrant is not 19485 required to be thread-safe. 19486 RETURN VALUE 19487 The hcreate( ) function shall return 0 if it cannot allocate sufficient space for the table; otherwise, 19488 it shall return non-zero. 19489 The hdestroy( ) function shall return no value. 19490 The hsearch( ) function shall return a null pointer if either the action is FIND and the item could 19491 not be found or the action is ENTER and the table is full. 19492 ERRORS 19493 The hcreate( ) and hsearch( ) functions may fail if: 19494 [ENOMEM] Insufficient storage space is available. | 19495 EXAMPLES 19496 The following example reads in strings followed by two numbers and stores them in a hash 19497 table, discarding duplicates. It then reads in strings and finds the matching entry in the hash 19498 table and prints it out. 19499 #include 19500 #include 19501 #include 19502 struct info { /* This is the info stored in the table */ 19503 int age, room; /* other than the key. */ 1094 Technical Standard (2000) (Draft July 31, 2000) System Interfaces hcreate( ) 19504 }; 19505 #define NUM_EMPL 5000 /* # of elements in search table. */ 19506 int main(void) 19507 { 19508 char string_space[NUM_EMPL*20]; /* Space to store strings. */ 19509 struct info info_space[NUM_EMPL]; /* Space to store employee info. */ 19510 char *str_ptr = string_space; /* Next space in string_space. */ 19511 struct info *info_ptr = info_space; 19512 /* Next space in info_space. */ 19513 ENTRY item; 19514 ENTRY *found_item; /* Name to look for in table. */ 19515 char name_to_find[30]; 19516 int i = 0; 19517 /* Create table; no error checking is performed. */ 19518 (void) hcreate(NUM_EMPL); 19519 while (scanf("%s%d%d", str_ptr, &info_ptr->age, 19520 &info_ptr->room) != EOF && i++ < NUM_EMPL) { 19521 /* Put information in structure, and structure in item. */ 19522 item.key = str_ptr; 19523 item.data = info_ptr; 19524 str_ptr += strlen(str_ptr) + 1; 19525 info_ptr++; 19526 /* Put item into table. */ 19527 (void) hsearch(item, ENTER); 19528 } 19529 /* Access table. */ 19530 item.key = name_to_find; 19531 while (scanf("%s", item.key) != EOF) { 19532 if ((found_item = hsearch(item, FIND)) != NULL) { 19533 /* If item is in the table. */ 19534 (void)printf("found %s, age = %d, room = %d\n", 19535 found_item->key, 19536 ((struct info *)found_item->data)->age, 19537 ((struct info *)found_item->data)->room); 19538 } else 19539 (void)printf("no such employee %s\n", name_to_find); 19540 } 19541 return 0; 19542 } 19543 APPLICATION USAGE 19544 The hcreate( ) and hsearch( ) functions may use malloc( ) to allocate space. 19545 RATIONALE 19546 None. System Interfaces, Issue 6 1095 hcreate( ) System Interfaces 19547 FUTURE DIRECTIONS 19548 None. 19549 SEE ALSO 19550 bsearch( ), lsearch( ), malloc( ), strcmp( ), tsearch( ), the Base Definitions volume of | 19551 IEEE Std. 1003.1-200x, | 19552 CHANGE HISTORY 19553 First released in Issue 1. Derived from Issue 1 of the SVID. | 19554 Issue 4 19555 In the SYNOPSIS section, the type of argument nel in the declaration of hcreate( ) is changed from 19556 unsigned to size_t, and the argument list is explicitly defined as void in the declaration of 19557 hdestroy( ). 19558 In the DESCRIPTION, the type of the comparison key is explicitly defined as char*, the type of 19559 item.data is explicitly defined as void*, and a statement is added indicating that hsearch( ) uses 19560 strcmp( ) as the comparison function. 19561 In the EXAMPLES section, the sample code is updated to use ISO C standard syntax. 19562 An ERRORS section is added and [ENOMEM] is defined as an error that may be returned by 19563 hsearch( ) and hcreate( ). 19564 Issue 6 19565 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 1096 Technical Standard (2000) (Draft July 31, 2000) System Interfaces htonl( ) 19566 NAME 19567 htonl, htons, ntohl, ntohs - convert values between host and network byte order 19568 SYNOPSIS 19569 #include 19570 uint32_t htonl(uint32_t hostlong); 19571 uint16_t htons(uint16_t hostshort); 19572 uint32_t ntohl(uint32_t netlong); 19573 uint16_t ntohs(uint16_t netshort); 19574 DESCRIPTION 19575 These functions shall convert 16-bit and 32-bit quantities between network byte order and host 19576 byte order. 19577 On some implementations, these functions are defined as macros. | 19578 The uint32_t and uint16_t types shall be defined as described in . | 19579 RETURN VALUE 19580 The htonl( ) and htons( ) functions shall return the argument value converted from host to 19581 network byte order. 19582 The ntohl( ) and ntohs( ) functions shall return the argument value converted from network to 19583 host byte order. 19584 ERRORS 19585 No errors are defined. 19586 EXAMPLES 19587 None. 19588 APPLICATION USAGE 19589 These functions are most often used in conjunction with IPv4 addresses and ports as returned by 19590 gethostent( ) and getservent( ). 19591 RATIONALE 19592 None. 19593 FUTURE DIRECTIONS 19594 None. 19595 SEE ALSO 19596 endhostent( ), endservent( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , | 19597 19598 CHANGE HISTORY 19599 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. | System Interfaces, Issue 6 1097 htons( ) System Interfaces 19600 NAME 19601 htons - convert values between host and network byte order 19602 SYNOPSIS 19603 #include 19604 uint16_t htons(uint16_t hostshort); 19605 DESCRIPTION 19606 Refer to htonl( ). 1098 Technical Standard (2000) (Draft July 31, 2000) System Interfaces hypot( ) 19607 NAME 19608 hypot, hypotf, hypotl - Euclidean distance function | 19609 SYNOPSIS 19610 XSI #include 19611 double hypot(double x, double y); 19612 float hypotf(float x, float y); | 19613 long double hypotl(long double x, long double y); | 19614 | 19615 DESCRIPTION 19616 These functions shall compute the value of the square root of x2+y2. | 19617 An application wishing to check for error situations should set errno to 0 before calling hypot( ). 19618 If errno is non-zero on return, or the return value is HUGE_VAL or NaN, an error has occurred. 19619 RETURN VALUE 19620 Upon successful completion, these functions shall return the length of the hypotenuse of a | 19621 right-angled triangle with sides of length x and y. | 19622 If the result would cause overflow, HUGE_VAL shall be returned and errno may be set to 19623 [ERANGE]. | 19624 If x or y is NaN, NaN shall be returned. and errno may be set to [EDOM]. | 19625 If the correct result would cause underflow, 0 shall be returned and errno may be set to 19626 [ERANGE]. 19627 ERRORS 19628 These functions may fail if: | 19629 [EDOM] The value of x or y is NaN. | 19630 [ERANGE] The result overflows or underflows. | 19631 No other errors shall occur. 19632 EXAMPLES 19633 None. 19634 APPLICATION USAGE 19635 The hypot( ) function takes precautions against overflow during intermediate steps of the 19636 computation. If the calculated result would still overflow a double, then hypot( ) shall return 19637 HUGE_VAL. 19638 RATIONALE 19639 None. 19640 FUTURE DIRECTIONS 19641 None. 19642 SEE ALSO 19643 isnan( ), sqrt( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 19644 CHANGE HISTORY 19645 First released in Issue 1. Derived from Issue 1 of the SVID. | System Interfaces, Issue 6 1099 hypot( ) System Interfaces 19646 Issue 4 19647 References to matherr( ) are removed. 19648 The RETURN VALUE and ERRORS sections are substantially rewritten to rationalize error 19649 handling in the mathematics functions. 19650 Issue 5 19651 The DESCRIPTION is updated to indicate how an application should check for an error. This 19652 text was previously published in the APPLICATION USAGE section. | 19653 Issue 6 | 19654 The hypotf( ) and hypotl( ) functions are added for alignment with the ISO/IEC 9899: 1999 | 19655 standard. | 1100 Technical Standard (2000) (Draft July 31, 2000) System Interfaces iconv( ) 19656 NAME 19657 iconv - codeset conversion function 19658 SYNOPSIS 19659 XSI #include 19660 size_t iconv(iconv_t cd, char **restrict inbuf, | 19661 size_t *restrict inbytesleft, char **restrict outbuf, | 19662 size_t *restrict outbytesleft); | 19663 | 19664 DESCRIPTION 19665 The iconv( ) function shall convert the sequence of characters from one codeset, in the array 19666 specified by inbuf, into a sequence of corresponding characters in another codeset, in the array 19667 specified by outbuf. The codesets are those specified in the iconv_open( ) call that returned the 19668 conversion descriptor, cd. The inbuf argument points to a variable that points to the first 19669 character in the input buffer and inbytesleft indicates the number of bytes to the end of the buffer 19670 to be converted. The outbuf argument points to a variable that points to the first available byte in 19671 the output buffer and outbytesleft indicates the number of the available bytes to the end of the 19672 buffer. 19673 For state-dependent encodings, the conversion descriptor cd is placed into its initial shift state by 19674 a call for which inbuf is a null pointer, or for which inbuf points to a null pointer. When iconv( ) is 19675 called in this way, and if outbuf is not a null pointer or a pointer to a null pointer, and outbytesleft 19676 points to a positive value, iconv( ) shall place, into the output buffer, the byte sequence to change 19677 the output buffer to its initial shift state. If the output buffer is not large enough to hold the 19678 entire reset sequence, iconv( ) shall fail and set errno to [E2BIG]. Subsequent calls with inbuf as | 19679 other than a null pointer or a pointer to a null pointer cause the conversion to take place from 19680 the current state of the conversion descriptor. 19681 If a sequence of input bytes does not form a valid character in the specified codeset, conversion 19682 stops after the previous successfully converted character. If the input buffer ends with an 19683 incomplete character or shift sequence, conversion stops after the previous successfully 19684 converted bytes. If the output buffer is not large enough to hold the entire converted input, 19685 conversion stops just prior to the input bytes that would cause the output buffer to overflow. 19686 The variable pointed to by inbuf is updated to point to the byte following the last byte 19687 successfully used in the conversion. The value pointed to by inbytesleft is decremented to reflect 19688 the number of bytes still not converted in the input buffer. The variable pointed to by outbuf is 19689 updated to point to the byte following the last byte of converted output data. The value pointed 19690 to by outbytesleft is decremented to reflect the number of bytes still available in the output buffer. 19691 For state-dependent encodings, the conversion descriptor is updated to reflect the shift state in 19692 effect at the end of the last successfully converted byte sequence. 19693 If iconv( ) encounters a character in the input buffer that is valid, but for which an identical 19694 character does not exist in the target codeset, iconv( ) performs an implementation-defined | 19695 conversion on this character. | 19696 RETURN VALUE 19697 The iconv( ) function shall update the variables pointed to by the arguments to reflect the extent 19698 of the conversion and return the number of non-identical conversions performed. If the entire 19699 string in the input buffer is converted, the value pointed to by inbytesleft shall be 0. If the input 19700 conversion is stopped due to any conditions mentioned above, the value pointed to by inbytesleft 19701 shall be non-zero and errno shall be set to indicate the condition. If an error occurs iconv( ) shall 19702 return (size_t)-1 and set errno to indicate the error. System Interfaces, Issue 6 1101 iconv( ) System Interfaces 19703 ERRORS 19704 The iconv( ) function shall fail if: 19705 [EILSEQ] Input conversion stopped due to an input byte that does not belong to the | 19706 input codeset. 19707 [E2BIG] Input conversion stopped due to lack of space in the output buffer. | 19708 [EINVAL] Input conversion stopped due to an incomplete character or shift sequence at | 19709 the end of the input buffer. 19710 The iconv( ) function may fail if: 19711 [EBADF] The cd argument is not a valid open conversion descriptor. | 19712 EXAMPLES 19713 None. 19714 APPLICATION USAGE 19715 The inbuf argument indirectly points to the memory area which contains the conversion input 19716 data. The outbuf argument indirectly points to the memory area which is to contain the result of 19717 the conversion. The objects indirectly pointed to by inbuf and outbuf are not restricted to 19718 containing data that is directly representable in the ISO C standard language char data type. The 19719 type of inbuf and outbuf, char**, does not imply that the objects pointed to are interpreted as 19720 null-terminated C strings or arrays of characters. Any interpretation of a byte sequence that 19721 represents a character in a given character set encoding scheme is done internally within the 19722 codeset converters. For example, the area pointed to indirectly by inbuf and/or outbuf can 19723 contain all zero octets that are not interpreted as string terminators but as coded character data 19724 according to the respective codeset encoding scheme. The type of the data (char, short, long, and | 19725 so on) read or stored in the objects is not specified, but may be inferred for both the input and 19726 output data by the converters determined by the fromcode and tocode arguments of iconv_open( ). 19727 Regardless of the data type inferred by the converter, the size of the remaining space in both 19728 input and output objects (the intbytesleft and outbytesleft arguments) is always measured in bytes. 19729 For implementations that support the conversion of state-dependent encodings, the conversion 19730 descriptor must be able to accurately reflect the shift-state in effect at the end of the last 19731 successful conversion. It is not required that the conversion descriptor itself be updated, which 19732 would require it to be a pointer type. Thus, implementations are free to implement the 19733 descriptor as a handle (other than a pointer type) by which the conversion information can be 19734 accessed and updated. 19735 RATIONALE 19736 None. 19737 FUTURE DIRECTIONS 19738 None. 19739 SEE ALSO 19740 iconv_open( ), iconv_close( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 19741 CHANGE HISTORY 19742 First released in Issue 4. Derived from the HP-UX Manual. | 19743 Issue 6 19744 The SYNOPSIS has been corrected to align with the reference page. | 19745 The restrict keyword is added to the iconv( ) prototype for alignment with the | 19746 ISO/IEC 9899: 1999 standard. | 1102 Technical Standard (2000) (Draft July 31, 2000) System Interfaces iconv_close( ) 19747 NAME 19748 iconv_close - codeset conversion deallocation function 19749 SYNOPSIS 19750 XSI #include 19751 int iconv_close(iconv_t cd); 19752 19753 DESCRIPTION 19754 The iconv_close( ) function deallocates the conversion descriptor cd and all other associated 19755 resources allocated by iconv_open( ). 19756 If a file descriptor is used to implement the type iconv_t, that file descriptor is closed. 19757 RETURN VALUE 19758 Upon successful completion, 0 shall be returned; otherwise, -1 shall be returned and errno set to 19759 indicate the error. 19760 ERRORS 19761 The iconv_close( ) function may fail if: 19762 [EBADF] The conversion descriptor is invalid. | 19763 EXAMPLES 19764 None. 19765 APPLICATION USAGE 19766 None. 19767 RATIONALE 19768 None. 19769 FUTURE DIRECTIONS 19770 None. 19771 SEE ALSO 19772 iconv( ), iconv_open( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 19773 CHANGE HISTORY 19774 First released in Issue 4. Derived from the HP-UX Manual. | System Interfaces, Issue 6 1103 iconv_open( ) System Interfaces 19775 NAME 19776 iconv_open - codeset conversion allocation function 19777 SYNOPSIS 19778 XSI #include 19779 iconv_t iconv_open(const char *tocode, const char *fromcode); 19780 19781 DESCRIPTION 19782 The iconv_open( ) function shall return a conversion descriptor that describes a conversion from 19783 the codeset specified by the string pointed to by the fromcode argument to the codeset specified 19784 by the string pointed to by the tocode argument. For state-dependent encodings, the conversion 19785 descriptor is in a codeset-dependent initial shift state, ready for immediate use with iconv( ). 19786 Settings of fromcode and tocode and their permitted combinations are implementation-defined. | 19787 A conversion descriptor remains valid until it is closed by iconv_close( ) or an implicit close. | 19788 If a file descriptor is used to implement conversion descriptors, the FD_CLOEXEC flag shall be 19789 set; see . 19790 RETURN VALUE 19791 Upon successful completion, iconv_open( ) shall return a conversion descriptor for use on 19792 subsequent calls to iconv( ). Otherwise, iconv_open( ) shall return (iconv_t)-1 and set errno to 19793 indicate the error. 19794 ERRORS 19795 The iconv_open( ) function may fail if: 19796 [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. | 19797 [ENFILE] Too many files are currently open in the system. | 19798 [ENOMEM] Insufficient storage space is available. | 19799 [EINVAL] The conversion specified by fromcode and tocode is not supported by the | 19800 implementation. 19801 EXAMPLES 19802 None. 19803 APPLICATION USAGE 19804 Some implementations of iconv_open( ) use malloc( ) to allocate space for internal buffer areas. 19805 The iconv_open( ) function may fail if there is insufficient storage space to accommodate these 19806 buffers. 19807 Portable applications must assume that conversion descriptors are not valid after a call to one of 19808 the exec functions. 19809 RATIONALE 19810 None. 19811 FUTURE DIRECTIONS 19812 None. 19813 SEE ALSO 19814 iconv( ), iconv_close( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , | 1104 Technical Standard (2000) (Draft July 31, 2000) System Interfaces iconv_open( ) 19815 CHANGE HISTORY 19816 First released in Issue 4. Derived from the HP-UX Manual. | System Interfaces, Issue 6 1105 if_freenameindex( ) System Interfaces 19817 NAME 19818 if_freenameindex - free memory allocated by ifnameindex( ) 19819 SYNOPSIS 19820 #include 19821 void if_freenameindex(struct if_nameindex *ptr); 19822 DESCRIPTION 19823 The if_freenameindex( ) function shall free the memory allocated by if_nameindex. The ptr | 19824 argument shall be a pointer that was returned by if_nameindex. After if_freenameindex( ) has been | 19825 called, the application should not use the array of which ptr is the address. 19826 RETURN VALUE 19827 None. 19828 ERRORS 19829 No errors are defined. | 19830 EXAMPLES 19831 None. 19832 APPLICATION USAGE 19833 None. 19834 RATIONALE 19835 None. 19836 FUTURE DIRECTIONS 19837 None. 19838 SEE ALSO 19839 getsockopt( ), if_indextoname( ), if_nameindex( ), if_nametoindex( ), setsockopt( ), the Base Definitions | 19840 volume of IEEE Std. 1003.1-200x, | 19841 CHANGE HISTORY 19842 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. | 1106 Technical Standard (2000) (Draft July 31, 2000) System Interfaces if_indextoname( ) 19843 NAME 19844 if_indextoname - map a network interface index to its corresponding name | 19845 SYNOPSIS 19846 #include 19847 char *if_indextoname(unsigned ifindex, char *ifname); | 19848 DESCRIPTION | 19849 The if_indextoname( ) function shall map an interface index to its corresponding name. | 19850 When this function is called, ifname shall point to a buffer of at least {IFNAMSIZ} bytes. The | 19851 function shall place in this buffer the name of the interface with index ifindex. | 19852 RETURN VALUE 19853 If ifindex is an interface index, then the function shall return the value supplied in ifname, which | 19854 points to a buffer now containing the interface name. Otherwise, the function shall return a | 19855 NULL pointer and set errno to indicate the error. | 19856 ERRORS 19857 The if_indextoname( ) function shall fail if: 19858 [ENXIO] The interface does not exist. | 19859 EXAMPLES 19860 None. 19861 APPLICATION USAGE 19862 None. 19863 RATIONALE 19864 None. 19865 FUTURE DIRECTIONS 19866 None. 19867 SEE ALSO 19868 getsockopt( ), if_freenameindex( ), if_nameindex( ), if_nametoindex( ), setsockopt( ), the Base | 19869 Definitions volume of IEEE Std. 1003.1-200x, | 19870 CHANGE HISTORY 19871 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. | System Interfaces, Issue 6 1107 if_nameindex( ) System Interfaces 19872 NAME 19873 if_nameindex - return all network interface names and indexes | 19874 SYNOPSIS 19875 #include 19876 struct if_nameindex *if_nameindex(void); 19877 DESCRIPTION 19878 The if_nameindex( ) function shall return an array of if_nameindex structures, one structure per | 19879 interface. The end of the array is indicated by a structure with an if_index field of zero and an | 19880 if_name field of NULL. 19881 Applications should call if_freenameindex( ) to release the memory that may be dynamically 19882 allocated by this function, after they have finished using it. 19883 RETURN VALUE 19884 Array of structures identifying local interfaces. A NULL pointer is returned upon an error, with | 19885 errno set to indicate the error. | 19886 ERRORS 19887 The if_nameindex( ) function may fail if: 19888 [ENOBUFS] Insufficient resources are available to complete the function. 19889 EXAMPLES 19890 None. 19891 APPLICATION USAGE 19892 None. 19893 RATIONALE 19894 None. 19895 FUTURE DIRECTIONS 19896 None. 19897 SEE ALSO 19898 getsockopt( ), if_freenameindex( ), if_indextoname( ), if_nametoindex( ), setsockopt( ), the Base | 19899 Definitions volume of IEEE Std. 1003.1-200x, | 19900 CHANGE HISTORY 19901 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. | 1108 Technical Standard (2000) (Draft July 31, 2000) System Interfaces if_nametoindex( ) 19902 NAME 19903 if_nametoindex - map a network interface name to its corresponding index | 19904 SYNOPSIS 19905 #include 19906 unsigned if_nametoindex(const char *ifname); | 19907 DESCRIPTION | 19908 The if_nametoindex( ) function shall return the interface index corresponding to name ifname. | 19909 RETURN VALUE 19910 The corresponding index if ifname is the name of an interface; otherwise, zero. | 19911 ERRORS 19912 No errors are defined. | 19913 EXAMPLES 19914 None. 19915 APPLICATION USAGE 19916 None. 19917 RATIONALE 19918 None. 19919 FUTURE DIRECTIONS 19920 None. 19921 SEE ALSO 19922 getsockopt( ), if_freenameindex( ), if_indextoname( ), if_nameindex( ), setsockopt( ), the Base | 19923 Definitions volume of IEEE Std. 1003.1-200x, | 19924 CHANGE HISTORY 19925 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. | System Interfaces, Issue 6 1109 ilogb( ) System Interfaces 19926 NAME 19927 ilogb, ilogbf, ilogbl - return an unbiased exponent | 19928 SYNOPSIS 19929 #include | 19930 int ilogb(double x); | 19931 int ilogbf(float x); | 19932 int ilogbl(long double x); | 19933 DESCRIPTION | 19934 These functions shall return the exponent part of x. Formally, the return value is the integral | 19935 part of logr | x | as a signed integral value, for non-zero x, where r is the radix of the machine's | 19936 floating point arithmetic, which is the value of FLT_RADIX defined in . | 19937 RETURN VALUE 19938 Upon successful completion, these functions shall return the exponent part of x as a signed | 19939 integer value. | 19940 If x is zero, these functions shall return the value FP_ILOGB0; if x is infinite, they shall return the | 19941 value {INT_MAX}; if x is a NaN, they shall return the value FP_ILOGBNAN; otherwise, they | 19942 shall be equivalent to calling the corresponding logb( ) function and casting the returned value to | 19943 type int. | 19944 ERRORS 19945 These functions may fail if: | 19946 [ERANGE] The value of x is 0. | 19947 EXAMPLES | 19948 None. 19949 APPLICATION USAGE 19950 None. 19951 RATIONALE 19952 None. 19953 FUTURE DIRECTIONS 19954 None. 19955 SEE ALSO 19956 logb( ), scalb( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , | 19957 CHANGE HISTORY 19958 First released in Issue 4, Version 2. 19959 Issue 5 19960 Moved from X/OPEN UNIX extension to BASE. | 19961 Issue 6 | 19962 The ilogbf( ) and ilogbl( ) functions are added for alignment with the ISO/IEC 9899: 1999 || 19963 standard. | 1110 Technical Standard (2000) (Draft July 31, 2000) System Interfaces imaxabs( ) 19964 NAME | 19965 imaxabs - return absolute value | 19966 SYNOPSIS | 19967 #include | 19968 intmax_t imaxabs(intmax_t j); | 19969 DESCRIPTION | 19970 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 19971 conflict between the requirements described here and the ISO C standard is unintentional. This | 19972 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 19973 The imaxabs( ) function shall compute the absolute value of an integer j. If the result cannot be | 19974 represented, the behavior is undefined. | 19975 RETURN VALUE | 19976 The imaxabs( ) function shall return the absolute value. | 19977 ERRORS | 19978 No errors are defined. | 19979 EXAMPLES | 19980 None. | 19981 APPLICATION USAGE | 19982 The absolute value of the most negative number cannot be represented in two's complement. | 19983 RATIONALE | 19984 None. | 19985 FUTURE DIRECTIONS | 19986 None. | 19987 SEE ALSO | 19988 imaxdiv( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 19989 CHANGE HISTORY || 19990 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 1111 imaxdiv( ) System Interfaces 19991 NAME | 19992 imaxdiv - return quotient and remainder | 19993 SYNOPSIS | 19994 #include | 19995 imaxdiv_t imaxdiv(intmax_t numer, intmax_t denom); | 19996 DESCRIPTION | 19997 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 19998 conflict between the requirements described here and the ISO C standard is unintentional. This | 19999 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 20000 The imaxdiv( ) function shall compute numer / denom and numer % denom in a single operation. | 20001 RETURN VALUE | 20002 The imaxdiv( ) function shall return a structure of type imaxdiv_t, comprising both the quotient | 20003 and the remainder. The structure shall contain (in either order) the members quot (the quotient) | 20004 and rem (the remainder), each of which has type intmax_t. | 20005 If either part of the result cannot be represented, the behavior is undefined. | 20006 ERRORS | 20007 No errors are defined. | 20008 EXAMPLES | 20009 None. | 20010 APPLICATION USAGE | 20011 None. | 20012 RATIONALE | 20013 None. | 20014 FUTURE DIRECTIONS | 20015 None. | 20016 SEE ALSO | 20017 imaxabs( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 20018 CHANGE HISTORY || 20019 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | 1112 Technical Standard (2000) (Draft July 31, 2000) System Interfaces index( ) 20020 NAME 20021 index - character string operations (LEGACY) 20022 SYNOPSIS 20023 XSI #include 20024 char *index(const char *s, int c); 20025 20026 DESCRIPTION 20027 The index( ) function is identical to strchr( ). 20028 RETURN VALUE 20029 See strchr( ). 20030 ERRORS 20031 See strchr( ). 20032 EXAMPLES 20033 None. 20034 APPLICATION USAGE 20035 strchr( ) is preferred over this function. 20036 For maximum portability, it is recommended to replace the function call to index( ) as follows: 20037 #define index(a,b) strchr((a),(b)) 20038 RATIONALE 20039 None. 20040 FUTURE DIRECTIONS 20041 This function may be withdrawn in a future version. 20042 SEE ALSO 20043 strchr( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 20044 CHANGE HISTORY 20045 First released in Issue 4, Version 2. 20046 Issue 5 20047 Moved from X/OPEN UNIX extension to BASE. 20048 Issue 6 20049 This function is marked LEGACY. System Interfaces, Issue 6 1113 inet_addr( ) System Interfaces 20050 NAME 20051 inet_addr, inet_lnaof (LEGACY), inet_makeaddr (LEGACY), inet_netof (LEGACY), 20052 inet_network (LEGACY), inet_ntoa - IPv4 address manipulation 20053 SYNOPSIS 20054 #include 20055 in_addr_t inet_addr(const char *cp); 20056 in_addr_t inet_lnaof(struct in_addr in); 20057 struct in_addr inet_makeaddr(in_addr_t net, in_addr_t lna); 20058 in_addr_t inet_netof(struct in_addr in); 20059 in_addr_t inet_network(const char *cp); 20060 char *inet_ntoa(struct in_addr in); 20061 DESCRIPTION 20062 The inet_addr( ) function shall convert the string pointed to by cp, in the standard IPv4 dotted 20063 decimal notation, to an integer value suitable for use as an Internet address. 20064 The inet_lnaof( ) function shall take an Internet host address specified by in and extract the local 20065 network address part, in host byte order. 20066 The inet_makeaddr( ) function shall take the Internet network number specified by net and the 20067 local network address specified by lna, both in host byte order, and construct an Internet address 20068 from them. 20069 The inet_netof( ) function shall take an Internet host address specified by in and extract the 20070 network number part, in host byte order. 20071 The inet_network( ) function shall convert the string pointed to by cp, in the standard IPv4 dotted 20072 decimal notation, to an integer value suitable for use as an Internet network number. 20073 The inet_ntoa( ) function shall convert the Internet host address specified by in to a string in the 20074 Internet standard dot notation. 20075 All Internet addresses shall be returned in network order (bytes ordered from left to right). 20076 Values specified using IPv4 dotted decimal notation take one of the following forms: 20077 a.b.c.d When four parts are specified, each is interpreted as a byte of data and assigned, 20078 from left to right, to the four bytes of an Internet address. 20079 a.b.c When a three-part address is specified, the last part is interpreted as a 16-bit 20080 quantity and placed in the rightmost two bytes of the network address. This makes 20081 the three-part address format convenient for specifying Class B network addresses 20082 as 128.net.host. 20083 a.b When a two-part address is supplied, the last part is interpreted as a 24-bit 20084 quantity and placed in the rightmost three bytes of the network address. This 20085 makes the two-part address format convenient for specifying Class A network 20086 addresses as net.host. 20087 a When only one part is given, the value is stored directly in the network address 20088 without any byte rearrangement. 20089 All numbers supplied as parts in IPv4 dotted decimal notation may be decimal, octal, or 20090 hexadecimal, as specified in the ISO C standard (that is, a leading "0x" or "0X" implies 20091 hexadecimal; otherwise, a leading '0' implies octal; otherwise, the number is interpreted as 20092 decimal). 1114 Technical Standard (2000) (Draft July 31, 2000) System Interfaces inet_addr( ) 20093 RETURN VALUE 20094 Upon successful completion, inet_addr( ) shall return the Internet address. Otherwise, it shall 20095 return (in_addr_t)(-1). 20096 The inet_lnaof( ) function shall return the local network address part. 20097 The inet_makeaddr( ) function shall return the constructed Internet address. 20098 The inet_netof( ) function shall return the network number. 20099 Upon successful completion, inet_network( ) shall return the converted Internet network number. 20100 Otherwise, it shall return (in_addr_t)(-1). 20101 The inet_ntoa( ) function shall return a pointer to the network address in Internet standard dot 20102 notation. 20103 ERRORS 20104 No errors are defined. 20105 EXAMPLES 20106 None. 20107 APPLICATION USAGE 20108 The inet_lnaof( ), inet_makeaddr( ), inet_netof( ), and inet_network( ) functions are marked LEGACY 20109 and should not be used by new applications. 20110 The return value of inet_ntoa( ) may point to static data that may be overwritten by subsequent 20111 calls to inet_ntoa( ). 20112 RATIONALE 20113 None. 20114 FUTURE DIRECTIONS 20115 The inet_lnaof( ), inet_makeaddr( ), inet_netof( ), and inet_network( ) functions may be withdrawn in | 20116 a future version. | 20117 SEE ALSO 20118 endhostent( ), endnetent( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 20119 CHANGE HISTORY 20120 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. | System Interfaces, Issue 6 1115 inet_lnaof( ) System Interfaces 20121 NAME 20122 inet_lnaof - IPv4 address manipulation 20123 SYNOPSIS 20124 #include 20125 in_addr_t inet_lnaof(struct in_addr in); 20126 DESCRIPTION 20127 Refer to inet_addr( ). 1116 Technical Standard (2000) (Draft July 31, 2000) System Interfaces inet_makeaddr( ) 20128 NAME 20129 inet_makeaddr - IPv4 address manipulation 20130 SYNOPSIS 20131 #include 20132 struct in_addr inet_makeaddr(in_addr_t net, in_addr_t lna); 20133 DESCRIPTION 20134 Refer to inet_addr( ). System Interfaces, Issue 6 1117 inet_netof( ) System Interfaces 20135 NAME 20136 inet_netof - IPv4 address manipulation 20137 SYNOPSIS 20138 #include 20139 in_addr_t inet_netof(struct in_addr in); 20140 DESCRIPTION 20141 Refer to inet_addr( ). 1118 Technical Standard (2000) (Draft July 31, 2000) System Interfaces inet_network( ) 20142 NAME 20143 inet_network - IPv4 address manipulation 20144 SYNOPSIS 20145 #include 20146 in_addr_t inet_network(const char *cp); 20147 DESCRIPTION 20148 Refer to inet_addr( ). System Interfaces, Issue 6 1119 inet_ntoa( ) System Interfaces 20149 NAME 20150 inet_ntoa - IPv4 address manipulation 20151 SYNOPSIS 20152 #include 20153 char *inet_ntoa(struct in_addr in); 20154 DESCRIPTION 20155 Refer to inet_addr( ). 1120 Technical Standard (2000) (Draft July 31, 2000) System Interfaces inet_ntop( ) 20156 NAME 20157 inet_ntop, inet_pton - convert IPv4 and IPv6 addresses between binary and text form 20158 SYNOPSIS 20159 IP6 #include 20160 const char *inet_ntop(int af, const void *restrict src, | 20161 char *restrict dst, socklen_t size); | 20162 int inet_pton(int af, const char *restrict src, void *restrict dst); | 20163 | 20164 Notes to Reviewers | 20165 This section with side shading will not appear in the final copy. - Ed. | 20166 D3, XSH, ERN 330 (AI 2000-05-024) To supply editing instructions regarding making these | 20167 functions mandatory and shading IPv6-specific information. | 20168 DESCRIPTION | 20169 The inet_ntop( ) function converts a numeric address into a text string suitable for presentation. 20170 The af argument specifies the family of the address. This can be AF_INET or AF_INET6. The src 20171 argument points to a buffer holding an IPv4 address if the af argument is AF_INET, or an IPv6 20172 address if the af argument is AF_INET6. The dst argument points to a buffer where the function 20173 stores the resulting text string; it shall not be NULL. The size argument specifies the size of this 20174 buffer, which shall be large enough to hold the text string (INET_ADDRSTRLEN characters for 20175 IPv4, INET6_ADDRSTRLEN characters for IPv6). 20176 The inet_pton( ) function converts an address in its standard text presentation form into its 20177 numeric binary form. The af argument specifies the family of the address. The AF_INET and 20178 AF_INET6 address families are supported. The src argument points to the string being passed in. 20179 The dst argument points to a buffer into which the function stores the numeric address; this shall 20180 be large enough to hold the numeric address (32 bits for AF_INET, 128 bits for AF_INET6). 20181 If the af argument of inet_pton( ) is AF_INET, the src string shall be in the standard IPv4 dotted- 20182 decimal form: 20183 ddd.ddd.ddd.ddd 20184 where "ddd" is a one to three digit decimal number between 0 and 255 (see inet_addr( )). The 20185 inet_pton( ) function does not accept other formats (such as the octal numbers, hexadecimal 20186 numbers, and fewer than four numbers that inet_addr( ) accepts). 20187 If the af argument of inet_pton( ) is AF_INET6, the src string shall be in one of the following 20188 standard IPv6 text forms: 20189 1. The preferred form is "x:x:x:x:x:x:x:x", where the 'x's are the hexadecimal values 20190 of the eight 16-bit pieces of the address. Leading zeros in individual fields can be omitted, 20191 but there shall be at least one numeral in every field. 20192 2. A string of contiguous zero fields in the preferred form can be shown as "::". The "::" 20193 can only appear once in an address. Unspecified addresses ("0:0:0:0:0:0:0:0") may 20194 be represented simply as "::". 20195 3. A third form that is sometimes more convenient when dealing with a mixed environment 20196 of IPv4 and IPv6 nodes is "x:x:x:x:x:x:d.d.d.d", where the 'x's are the 20197 hexadecimal values of the six high-order 16-bit pieces of the address, and the 'd's are the 20198 decimal values of the four low-order 8-bit pieces of the address (standard IPv4 20199 representation). System Interfaces, Issue 6 1121 inet_ntop( ) System Interfaces 20200 Note: A more extensive description of the standard representations of IPv6 addresses can 20201 be found in RFC 2373. 20202 RETURN VALUE 20203 The inet_ntop( ) function shall return a pointer to the buffer containing the text string if the | 20204 conversion succeeds, and NULL otherwise, and set errno to indicate the error. | 20205 The inet_pton( ) function shall return 1 if the conversion succeeds, with the address pointed to by 20206 dst in network byte order. It shall return 0 if the input is not a valid IPv4 dotted-decimal string or 20207 a valid IPv6 address string, or -1 with errno set to [EAFNOSUPPORT] if the af argument is 20208 unknown. 20209 ERRORS 20210 The inet_ntop( ) and inet_pton( ) functions shall fail if: 20211 [EAFNOSUPPORT] 20212 The af argument is invalid. 20213 [ENOSPC] The size of the inet_ntop( ) result buffer is inadequate. 20214 EXAMPLES 20215 None. 20216 APPLICATION USAGE 20217 None. 20218 RATIONALE 20219 None. 20220 FUTURE DIRECTIONS 20221 None. 20222 SEE ALSO 20223 The Base Definitions volume of IEEE Std. 1003.1-200x, | 20224 CHANGE HISTORY 20225 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. | 20226 Marked as part of the IPv6 option. | 20227 The restrict keyword is added to the inet_ntop( ) and inet_pton( ) prototypes for alignment with | 20228 the ISO/IEC 9899: 1999 standard. | 1122 Technical Standard (2000) (Draft July 31, 2000) System Interfaces initstate( ) 20229 NAME 20230 initstate, random, setstate, srandom - pseudorandom number functions 20231 SYNOPSIS 20232 XSI #include 20233 char *initstate(unsigned seed, char *state, size_t size); | 20234 long random(void); | 20235 char *setstate(const char *state); 20236 void srandom(unsigned seed); | 20237 | 20238 DESCRIPTION 20239 The random( ) function uses a non-linear additive feedback random-number generator | 20240 employing a default state array size of 31 long integers to return successive pseudo-random | 20241 numbers in the range from 0 to 231-1. The period of this random-number generator is | 20242 approximately 16 x (231-1). The size of the state array determines the period of the random- 20243 number generator. Increasing the state array size increases the period. 20244 With 256 bytes of state information, the period of the random-number generator is greater than 20245 269. 20246 Like rand( ), random( ) produces by default a sequence of numbers that can be duplicated by 20247 calling srandom( ) with 1 as the seed. 20248 The srandom( ) function initializes the current state array using the value of seed. 20249 The initstate( ) and setstate( ) functions handle restarting and changing random-number 20250 generators. The initstate( ) function allows a state array, pointed to by the state argument, to be 20251 initialized for future use. The size argument, which specifies the size in bytes of the state array, is 20252 used by initstate( ) to decide what type of random-number generator to use; the larger the state 20253 array, the more random the numbers. Values for the amount of state information are 8, 32, 64, 20254 128, and 256 bytes. Other values greater than 8 bytes are rounded down to the nearest one of 20255 these values. If initstate( ) is called with 8 size<32, then random( ) uses a simple linear 20256 congruential random number generator. The seed argument specifies a starting point for the 20257 random-number sequence and provides for restarting at the same point. The initstate( ) function 20258 shall return a pointer to the previous state information array. 20259 If initstate( ) has not been called, then random( ) behaves as though initstate( ) had been called 20260 with seed=1 and size=128. 20261 Once a state has been initialized, setstate( ) allows switching between state arrays. The array 20262 defined by the state argument is used for further random-number generation until initstate( ) is 20263 called or setstate( ) is called again. The setstate( ) function shall return a pointer to the previous 20264 state array. 20265 RETURN VALUE 20266 If initstate( ) is called with size less than 8, it shall return NULL. 20267 The random( ) function shall return the generated pseudo-random number. 20268 The srandom( ) function shall return no value. 20269 Upon successful completion, initstate( ) and setstate( ) shall return a pointer to the previous state 20270 array; otherwise, a null pointer shall be returned. System Interfaces, Issue 6 1123 initstate( ) System Interfaces 20271 ERRORS 20272 No errors are defined. 20273 EXAMPLES 20274 None. 20275 APPLICATION USAGE 20276 After initialization, a state array can be restarted at a different point in one of two ways: 20277 1. The initstate( ) function can be used, with the desired seed, state array, and size of the 20278 array. 20279 2. The setstate( ) function, with the desired state, can be used, followed by srandom( ) with the 20280 desired seed. The advantage of using both of these functions is that the size of the state 20281 array does not have to be saved once it is initialized. 20282 Although some implementations of random( ) have written messages to standard error, such 20283 implementations do not conform to this volume of IEEE Std. 1003.1-200x. 20284 Issue 5 restores the historical behavior of this function. 20285 Threaded applications should use rand_r( ), erand48( ), nrand48( ), or jrand48( ) instead of 20286 random( ) when an independent random number sequence in multiple threads is required. 20287 RATIONALE 20288 None. 20289 FUTURE DIRECTIONS 20290 None. 20291 SEE ALSO 20292 drand48( ), rand( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 20293 CHANGE HISTORY 20294 First released in Issue 4, Version 2. 20295 Issue 5 20296 Moved from X/OPEN UNIX extension to BASE. 20297 In the DESCRIPTION, the phrase ``values smaller than 8'' is replaced with ``values greater than 20298 or equal to 8, or less than 32'', ``size<8'' is replaced with ``8 size <32'', and a new first paragraph 20299 is added to the RETURN VALUE section. A note is added to the APPLICATION USAGE 20300 indicating that these changes restore the historical behavior of the function. 20301 Issue 6 20302 In the DESCRIPTION, duplicate text ``For values greater than or equal to 8 . . .'' is removed. 1124 Technical Standard (2000) (Draft July 31, 2000) System Interfaces insque( ) 20303 NAME 20304 insque, remque - insert or remove an element in a queue 20305 SYNOPSIS 20306 XSI #include 20307 void insque(void *element, void *pred); 20308 void remque(void *element); 20309 20310 DESCRIPTION 20311 The insque( ) and remque( ) functions manipulate queues built from doubly-linked lists. The 20312 queue can be either circular or linear. An application using insque( ) or remque( ) shall ensure it 20313 defines a structure in which the first two members of the structure are pointers to the same type 20314 of structure, and any further members are application-specific. The first member of the structure 20315 is a forward pointer to the next entry in the queue. The second member is a backward pointer to 20316 the previous entry in the queue. If the queue is linear, the queue is terminated with null 20317 pointers. The names of the structure and of the pointer members are not subject to any special 20318 restriction. 20319 The insque( ) function inserts the element pointed to by element into a queue immediately after 20320 the element pointed to by pred. 20321 The remque( ) function removes the element pointed to by element from a queue. 20322 If the queue is to be used as a linear list, invoking insque(&element, NULL), where element is the 20323 initial element of the queue, shall initialize the forward and backward pointers of element to null 20324 pointers. 20325 If the queue is to be used as a circular list, the application shall ensure it initializes the forward 20326 pointer and the backward pointer of the initial element of the queue to the element's own 20327 address. 20328 RETURN VALUE 20329 The insque( ) and remque( ) functions do not return a value. 20330 ERRORS 20331 No errors are defined. 20332 EXAMPLES 20333 Creating a Linear Linked List 20334 The following example creates a linear linked list. 20335 #include 20336 ... 20337 struct myque element1; 20338 struct myque element2; 20339 char *data1 = "DATA1"; 20340 char *data2 = "DATA2"; 20341 ... 20342 element1.data = data1; 20343 element2.data = data2; 20344 insque (&element1, NULL); 20345 insque (&element2, &element1); System Interfaces, Issue 6 1125 insque( ) System Interfaces 20346 Creating a Circular Linked List 20347 The following example creates a circular linked list. 20348 #include 20349 ... 20350 struct myque element1; 20351 struct myque element2; 20352 char *data1 = "DATA1"; 20353 char *data2 = "DATA2"; 20354 ... 20355 element1.data = data1; 20356 element2.data = data2; 20357 element1.fwd = &element1; 20358 element1.bck = &element1; 20359 insque (&element2, &element1); 20360 Removing an Element 20361 The following example removes the element pointed to by element1. 20362 #include 20363 ... 20364 struct myque element1; 20365 ... 20366 remque (&element1); 20367 APPLICATION USAGE 20368 The historical implementations of these functions described the arguments as being of type 20369 struct qelem* rather than as being of type void* as defined here. In those implementations, 20370 struct qelem was commonly defined in as: 20371 struct qelem { 20372 struct qelem *q_forw; 20373 struct qelem *q_back; 20374 }; 20375 Applications using these functions, however, were never able to use this structure directly since 20376 it provided no room for the actual data contained in the elements. Most applications defined 20377 structures that contained the two pointers as the initial elements and also provided space for, or 20378 pointers to, the object's data. Applications that used these functions to update more than one 20379 type of table also had the problem of specifying two or more different structures with the same 20380 name, if they literally used struct qelem as specified. 20381 As described here, the implementations were actually expecting a structure type where the first 20382 two members were forward and backward pointers to structures. With C compilers that didn't 20383 provide function prototypes, applications used structures as specified in the DESCRIPTION 20384 above and the compiler did what the application expected. 20385 If this method had been carried forward with an ISO C standard compiler and the historical 20386 function prototype, most applications would have to be modified to cast pointers to the 20387 structures actually used to be pointers to struct qelem to avoid compilation warnings. By 20388 specifying void* as the argument type, applications do not need to change (unless they 20389 specifically referenced struct qelem and depended on it being defined in ). 1126 Technical Standard (2000) (Draft July 31, 2000) System Interfaces insque( ) 20390 RATIONALE 20391 None. 20392 FUTURE DIRECTIONS 20393 None. 20394 SEE ALSO 20395 The Base Definitions volume of IEEE Std. 1003.1-200x, | 20396 CHANGE HISTORY 20397 First released in Issue 4, Version 2. 20398 Issue 5 20399 Moved from X/OPEN UNIX extension to BASE. 20400 Issue 6 20401 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1127 ioctl( ) System Interfaces 20402 NAME 20403 ioctl - control a STREAMS device (STREAMS) 20404 SYNOPSIS 20405 XSR #include 20406 int ioctl(int fildes, int request, ... /* arg */); 20407 20408 DESCRIPTION 20409 The ioctl( ) function performs a variety of control functions on STREAMS devices. For non- 20410 STREAMS devices, the functions performed by this call are unspecified. The request argument 20411 and an optional third argument (with varying type) are passed to and interpreted by the 20412 appropriate part of the STREAM associated with fildes. 20413 The fildes argument is an open file descriptor that refers to a device. 20414 The request argument selects the control function to be performed and shall depend on the 20415 STREAMS device being addressed. 20416 The arg argument represents additional information that is needed by this specific STREAMS 20417 device to perform the requested function. The type of arg depends upon the particular control 20418 request, but it is either an integer or a pointer to a device-specific data structure. 20419 The ioctl( ) commands applicable to STREAMS, their arguments, and error conditions that apply 20420 to each individual command are described below. 20421 The following ioctl( ) commands, with error values indicated, are applicable to all STREAMS 20422 files: 20423 I_PUSH Pushes the module whose name is pointed to by arg onto the top of the 20424 current STREAM, just below the STREAM head. It then calls the open( ) 20425 function of the newly-pushed module. 20426 The ioctl( ) function with the I_PUSH command shall fail if: 20427 [EINVAL] Invalid module name. | 20428 [ENXIO] Open function of new module failed. | 20429 [ENXIO] Hangup received on fildes. | 20430 I_POP Removes the module just below the STREAM head of the STREAM pointed to 20431 by fildes. The arg argument should be 0 in an I_POP request. 20432 The ioctl( ) function with the I_POP command shall fail if: 20433 [EINVAL] No module present in the STREAM. | 20434 [ENXIO] Hangup received on fildes. | 20435 I_LOOK Retrieves the name of the module just below the STREAM head of the 20436 STREAM pointed to by fildes, and places it in a character string pointed to by 20437 arg. The buffer pointed to by arg should be at least FMNAMESZ+1 bytes long, 20438 where FMNAMESZ is defined in . 20439 The ioctl( ) function with the I_LOOK command shall fail if: 20440 [EINVAL] No module present in the STREAM. | 20441 I_FLUSH This request flushes read and/or write queues, depending on the value of arg. 20442 Valid arg values are: 1128 Technical Standard (2000) (Draft July 31, 2000) System Interfaces ioctl( ) 20443 FLUSHR Flush all read queues. 20444 FLUSHW Flush all write queues. 20445 FLUSHRW Flush all read and all write queues. 20446 The ioctl( ) function with the I_FLUSH command shall fail if: 20447 [EINVAL] Invalid arg value. | 20448 [EAGAIN] or [ENOSR] | 20449 Unable to allocate buffers for flush message. 20450 [ENXIO] Hangup received on fildes. | 20451 I_FLUSHBAND Flushes a particular band of messages. The arg argument points to a bandinfo 20452 structure. The bi_flag member may be one of FLUSHR, FLUSHW, or 20453 FLUSHRW as described above. The bi_pri member determines the priority 20454 band to be flushed. 20455 I_SETSIG Requests that the STREAMS implementation send the SIGPOLL signal to the 20456 calling process when a particular event has occurred on the STREAM 20457 associated with fildes. I_SETSIG supports an asynchronous processing 20458 capability in STREAMS. The value of arg is a bitmask that specifies the events 20459 for which the process should be signaled. It is the bitwise-inclusive OR of any 20460 combination of the following constants: 20461 S_RDNORM A normal (priority band set to 0) message has arrived at the 20462 head of a STREAM head read queue. A signal shall be 20463 generated even if the message is of zero length. 20464 S_RDBAND A message with a non-zero priority band has arrived at the 20465 head of a STREAM head read queue. A signal shall be 20466 generated even if the message is of zero length. 20467 S_INPUT A message, other than a high-priority message, has arrived 20468 at the head of a STREAM head read queue. A signal shall be 20469 generated even if the message is of zero length. 20470 S_HIPRI A high-priority message is present on a STREAM head read 20471 queue. A signal shall be generated even if the message is of 20472 zero length. 20473 S_OUTPUT The write queue for normal data (priority band 0) just 20474 below the STREAM head is no longer full. This notifies the 20475 process that there is room on the queue for sending (or 20476 writing) normal data downstream. 20477 S_WRNORM Same as S_OUTPUT. 20478 S_WRBAND The write queue for a non-zero priority band just below the 20479 STREAM head is no longer full. This notifies the process 20480 that there is room on the queue for sending (or writing) 20481 priority data downstream. 20482 S_MSG A STREAMS signal message that contains the SIGPOLL 20483 signal has reached the front of the STREAM head read 20484 queue. 20485 S_ERROR Notification of an error condition has reached the STREAM 20486 head. System Interfaces, Issue 6 1129 ioctl( ) System Interfaces 20487 S_HANGUP Notification of a hangup has reached the STREAM head. 20488 S_BANDURG When used in conjunction with S_RDBAND, SIGURG is 20489 generated instead of SIGPOLL when a priority message 20490 reaches the front of the STREAM head read queue. 20491 If arg is 0, the calling process shall be unregistered and shall not receive 20492 further SIGPOLL signals for the stream associated with fildes. 20493 Processes that wish to receive SIGPOLL signals shall ensure that they 20494 explicitly register to receive them using I_SETSIG. If several processes register 20495 to receive this signal for the same event on the same STREAM, each process 20496 shall be signaled when the event occurs. 20497 The ioctl( ) function with the I_SETSIG command shall fail if: 20498 [EINVAL] The value of arg is invalid. | 20499 [EINVAL] The value of arg is 0 and the calling process is not registered | 20500 to receive the SIGPOLL signal. 20501 [EAGAIN] There were insufficient resources to store the signal request. | 20502 I_GETSIG Returns the events for which the calling process is currently registered to be 20503 sent a SIGPOLL signal. The events are returned as a bitmask in an int pointed 20504 to by arg, where the events are those specified in the description of I_SETSIG 20505 above. 20506 The ioctl( ) function with the I_GETSIG command shall fail if: 20507 [EINVAL] Process is not registered to receive the SIGPOLL signal. | 20508 I_FIND This request compares the names of all modules currently present in the 20509 STREAM to the name pointed to by arg, and returns 1 if the named module is 20510 present in the STREAM, or returns 0 if the named module is not present. 20511 The ioctl( ) function with the I_FIND command shall fail if: 20512 [EINVAL] arg does not contain a valid module name. | 20513 I_PEEK This request allows a process to retrieve the information in the first message 20514 on the STREAM head read queue without taking the message off the queue. It 20515 is analogous to getmsg( ) except that this command does not remove the 20516 message from the queue. The arg argument points to a strpeek structure. 20517 The application shall ensure that the maxlen member in the ctlbuf and databuf 20518 strbuf structures is set to the number of bytes of control information and/or 20519 data information, respectively, to retrieve. The flags member may be marked 20520 RS_HIPRI or 0, as described by getmsg( ). If the process sets flags to RS_HIPRI, 20521 for example, I_PEEK shall only look for a high-priority message on the 20522 STREAM head read queue. 20523 I_PEEK returns 1 if a message was retrieved, and returns 0 if no message was 20524 found on the STREAM head read queue, or if the RS_HIPRI flag was set in 20525 flags and a high-priority message was not present on the STREAM head read 20526 queue. It does not wait for a message to arrive. On return, ctlbuf specifies 20527 information in the control buffer, databuf specifies information in the data 20528 buffer, and flags contains the value RS_HIPRI or 0. 20529 I_SRDOPT Sets the read mode using the value of the argument arg. Read modes are 20530 described in read( ). Valid arg flags are: 1130 Technical Standard (2000) (Draft July 31, 2000) System Interfaces ioctl( ) 20531 RNORM Byte-stream mode, the default. 20532 RMSGD Message-discard mode. 20533 RMSGN Message-nondiscard mode. 20534 The bitwise-inclusive OR of RMSGD and RMSGN shall return [EINVAL]. The | 20535 bitwise-inclusive OR of RNORM and either RMSGD or RMSGN shall result in 20536 the other flag overriding RNORM which is the default. 20537 In addition, treatment of control messages by the STREAM head may be 20538 changed by setting any of the following flags in arg: 20539 RPROTNORM Fail read( ) with [EBADMSG] if a message containing a 20540 control part is at the front of the STREAM head read queue. | 20541 RPROTDAT Deliver the control part of a message as data when a 20542 process issues a read( ). 20543 RPROTDIS Discard the control part of a message, delivering any data 20544 portion, when a process issues a read( ). 20545 The ioctl( ) function with the I_SRDOPT command shall fail if: 20546 [EINVAL] The arg argument is not valid. | 20547 I_GRDOPT Returns the current read mode setting as, described above, in an int pointed to 20548 by the argument arg. Read modes are described in read( ). 20549 I_NREAD Counts the number of data bytes in the data part of the first message on the 20550 STREAM head read queue and places this value in the int pointed to by arg. 20551 The return value for the command is the number of messages on the STREAM 20552 head read queue. For example, if 0 is returned in arg, but the ioctl( ) return 20553 value is greater than 0, this indicates that a zero-length message is next on the 20554 queue. 20555 I_FDINSERT Creates a message from specified buffer(s), adds information about another 20556 STREAM, and sends the message downstream. The message contains a 20557 control part and an optional data part. The data and control parts to be sent 20558 are distinguished by placement in separate buffers, as described below. The 20559 arg argument points to a strfdinsert structure. 20560 The application shall ensure that the len member in the ctlbuf strbuf structure 20561 is set to the size of a t_uscalar_t plus the number of bytes of control 20562 information to be sent with the message. The fildes member specifies the file 20563 descriptor of the other STREAM, and the offset member, which must be 20564 suitably aligned for use as a t_uscalar_t, specifies the offset from the start of 20565 the control buffer where I_FDINSERT shall store a t_uscalar_t whose 20566 interpretation is specific to the STREAM end. The application shall ensure that 20567 the len member in the databuf strbuf structure is set to the number of bytes of 20568 data information to be sent with the message, or to 0 if no data part is to be 20569 sent. 20570 The flags member specifies the type of message to be created. A normal 20571 message is created if flags is set to 0, and a high-priority message is created if 20572 flags is set to RS_HIPRI. For non-priority messages, I_FDINSERT shall block if 20573 the STREAM write queue is full due to internal flow control conditions. For 20574 priority messages, I_FDINSERT does not block on this condition. For non- 20575 priority messages, I_FDINSERT does not block when the write queue is full System Interfaces, Issue 6 1131 ioctl( ) System Interfaces 20576 and O_NONBLOCK is set. Instead, it fails and sets errno to [EAGAIN]. | 20577 I_FDINSERT also blocks, unless prevented by lack of internal resources, 20578 waiting for the availability of message blocks in the STREAM, regardless of 20579 priority or whether O_NONBLOCK has been specified. No partial message is 20580 sent. 20581 The ioctl( ) function with the I_FDINSERT command shall fail if: 20582 [EAGAIN] A non-priority message is specified, the O_NONBLOCK | 20583 flag is set, and the STREAM write queue is full due to 20584 internal flow control conditions. 20585 [EAGAIN] or [ENOSR] | 20586 Buffers cannot be allocated for the message that is to be 20587 created. 20588 [EINVAL] One of the following: | 20589 - The fildes member of the strfdinsert structure is not a 20590 valid, open STREAM file descriptor. 20591 - The size of a t_uscalar_t plus offset is greater than the len 20592 member for the buffer specified through ctlbuf. 20593 - The offset member does not specify a properly-aligned 20594 location in the data buffer. 20595 - An undefined value is stored in flags. 20596 [ENXIO] Hangup received on the STREAM identified by either the | 20597 fildes argument or the fildes member of the strfdinsert 20598 structure. 20599 [ERANGE] The len member for the buffer specified through databuf | 20600 does not fall within the range specified by the maximum 20601 and minimum packet sizes of the topmost STREAM module 20602 or the len member for the buffer specified through databuf 20603 is larger than the maximum configured size of the data part 20604 of a message; or the len member for the buffer specified 20605 through ctlbuf is larger than the maximum configured size 20606 of the control part of a message. 20607 I_STR Constructs an internal STREAMS ioctl( ) message from the data pointed to by 20608 arg, and sends that message downstream. 20609 This mechanism is provided to send ioctl( ) requests to downstream modules 20610 and drivers. It allows information to be sent with ioctl( ), and returns to the 20611 process any information sent upstream by the downstream recipient. I_STR 20612 blocks until the system responds with either a positive or negative 20613 acknowledgement message, or until the request times out after some period of 20614 time. If the request times out, it fails with errno set to [ETIME]. | 20615 At most, one I_STR can be active on a STREAM. Further I_STR calls shall 20616 block until the active I_STR completes at the STREAM head. The default 20617 timeout interval for these requests is 15 seconds. The O_NONBLOCK flag has 20618 no effect on this call. 20619 To send requests downstream, the application shall ensure that arg points to a 20620 strioctl structure. 1132 Technical Standard (2000) (Draft July 31, 2000) System Interfaces ioctl( ) 20621 The ic_cmd member is the internal ioctl( ) command intended for a 20622 downstream module or driver and ic_timout is the number of seconds 20623 (-1=infinite, 0=use implementation-defined timeout interval, >0=as specified) | 20624 an I_STR request shall wait for acknowledgement before timing out. ic_len is | 20625 the number of bytes in the data argument, and ic_dp is a pointer to the data 20626 argument. The ic_len member has two uses: on input, it contains the length of 20627 the data argument passed in, and on return from the command, it contains the 20628 number of bytes being returned to the process (the buffer pointed to by ic_dp 20629 should be large enough to contain the maximum amount of data that any 20630 module or the driver in the STREAM can return). 20631 The STREAM head shall convert the information pointed to by the strioctl 20632 structure to an internal ioctl( ) command message and sends it downstream. 20633 The ioctl( ) function with the I_STR command shall fail if: 20634 [EAGAIN] or [ENOSR] | 20635 Unable to allocate buffers for the ioctl( ) message. 20636 [EINVAL] The ic_len member is less than 0 or larger than the | 20637 maximum configured size of the data part of a message, or 20638 ic_timout is less than -1. 20639 [ENXIO] Hangup received on fildes. | 20640 [ETIME] A downstream ioctl( ) timed out before acknowledgement | 20641 was received. 20642 An I_STR can also fail while waiting for an acknowledgement if a message 20643 indicating an error or a hangup is received at the STREAM head. In addition, 20644 an error code can be returned in the positive or negative acknowledgement 20645 message, in the event the ioctl( ) command sent downstream fails. For these 20646 cases, I_STR fails with errno set to the value in the message. 20647 I_SWROPT Sets the write mode using the value of the argument arg. Valid bit settings for 20648 arg are: 20649 SNDZERO Send a zero-length message downstream when a write( ) of 20650 0 bytes occurs. To not send a zero-length message when a 20651 write( ) of 0 bytes occurs, the application shall ensure that 20652 this bit is not set in arg (for example, arg would be set to 0). 20653 The ioctl( ) function with the I_SWROPT command shall fail if: 20654 [EINVAL] arg is not the above value. | 20655 I_GWROPT Returns the current write mode setting, as described above, in the int that is 20656 pointed to by the argument arg. 20657 I_SENDFD I_SENDFD creates a new reference to the open file description associated with 20658 the file descriptor arg, and writes a message on the STREAMS-based pipe 20659 fildes containing this reference, together with the user ID and group ID of the 20660 calling process. 20661 The ioctl( ) function with the I_SENDFD command shall fail if: 20662 [EAGAIN] The sending STREAM is unable to allocate a message block | 20663 to contain the file pointer; or the read queue of the receiving 20664 STREAM head is full and cannot accept the message sent by 20665 I_SENDFD. System Interfaces, Issue 6 1133 ioctl( ) System Interfaces 20666 [EBADF] The arg argument is not a valid, open file descriptor. | 20667 [EINVAL] The fildes argument is not connected to a STREAM pipe. | 20668 [ENXIO] Hangup received on fildes. | 20669 I_RECVFD Retrieves the reference to an open file description from a message written to a 20670 STREAMS-based pipe using the I_SENDFD command, and allocates a new 20671 file descriptor in the calling process that refers to this open file description. 20672 The arg argument is a pointer to a strrecvfd data structure as defined in 20673 . 20674 The fd member is a file descriptor. The uid and gid members are the effective 20675 user ID and effective group ID, respectively, of the sending process. 20676 If O_NONBLOCK is not set, I_RECVFD blocks until a message is present at 20677 the STREAM head. If O_NONBLOCK is set, I_RECVFD fails with errno set to 20678 [EAGAIN] if no message is present at the STREAM head. | 20679 If the message at the STREAM head is a message sent by an I_SENDFD, a new 20680 file descriptor is allocated for the open file descriptor referenced in the 20681 message. The new file descriptor is placed in the fd member of the strrecvfd 20682 structure pointed to by arg. 20683 The ioctl( ) function with the I_RECVFD command shall fail if: 20684 [EAGAIN] A message is not present at the STREAM head read queue | 20685 and the O_NONBLOCK flag is set. 20686 [EBADMSG] The message at the STREAM head read queue is not a | 20687 message containing a passed file descriptor. 20688 [EMFILE] The process has the maximum number of file descriptors | 20689 currently open that it is allowed. 20690 [ENXIO] Hangup received on fildes. | 20691 I_LIST This request allows the process to list all the module names on the STREAM, 20692 up to and including the topmost driver name. If arg is a null pointer, the 20693 return value is the number of modules, including the driver, that are on the 20694 STREAM pointed to by fildes. This lets the process allocate enough space for 20695 the module names. Otherwise, it should point to a str_list structure. 20696 The sl_nmods member indicates the number of entries the process has 20697 allocated in the array. Upon return, the sl_modlist member of the str_list 20698 structure contains the list of module names, and the number of entries that 20699 have been filled into the sl_modlist array is found in the sl_nmods member (the 20700 number includes the number of modules including the driver). The return 20701 value from ioctl( ) is 0. The entries are filled in starting at the top of the 20702 STREAM and continuing downstream until either the end of the STREAM is 20703 reached, or the number of requested modules (sl_nmods) is satisfied. 20704 The ioctl( ) function with the I_LIST command shall fail if: 20705 [EINVAL] The sl_nmods member is less than 1. | 20706 [EAGAIN] or [ENOSR] | 20707 Unable to allocate buffers. 20708 I_ATMARK This request allows the process to see if the message at the head of the 20709 STREAM head read queue is marked by some module downstream. The arg 1134 Technical Standard (2000) (Draft July 31, 2000) System Interfaces ioctl( ) 20710 argument determines how the checking is done when there may be multiple 20711 marked messages on the STREAM head read queue. It may take on the 20712 following values: 20713 ANYMARK Check if the message is marked. 20714 LASTMARK Check if the message is the last one marked on the queue. 20715 The bitwise-inclusive OR of the flags ANYMARK and LASTMARK is 20716 permitted. 20717 The return value is 1 if the mark condition is satisfied; otherwise, the value is 20718 0. 20719 The ioctl( ) function with the I_ATMARK command shall fail if: 20720 [EINVAL] Invalid arg value. | 20721 I_CKBAND Check if the message of a given priority band exists on the STREAM head 20722 read queue. This returns 1 if a message of the given priority exists, 0 if no such 20723 message exists, or -1 on error. arg should be of type int. 20724 The ioctl( ) function with the I_CKBAND command shall fail if: 20725 [EINVAL] Invalid arg value. | 20726 I_GETBAND Return the priority band of the first message on the STREAM head read queue 20727 in the integer referenced by arg. 20728 The ioctl( ) function with the I_GETBAND command shall fail if: 20729 [ENODATA] No message on the STREAM head read queue. | 20730 I_CANPUT Check if a certain band is writable. arg is set to the priority band in question. 20731 The return value is 0 if the band is flow-controlled, 1 if the band is writable, or 20732 -1 on error. 20733 The ioctl( ) function with the I_CANPUT command shall fail if: 20734 [EINVAL] Invalid arg value. | 20735 I_SETCLTIME This request allows the process to set the time the STREAM head shall delay 20736 when a STREAM is closing and there is data on the write queues. Before 20737 closing each module or driver, if there is data on its write queue, the STREAM 20738 head shall delay for the specified amount of time to allow the data to drain. If, 20739 after the delay, data is still present, it shall be flushed. The arg argument is a 20740 pointer to an integer specifying the number of milliseconds to delay, rounded 20741 up to the nearest valid value. If I_SETCLTIME is not performed on a STREAM, | 20742 an implementation-defined default timeout interval is used. | 20743 The ioctl( ) function with the I_SETCLTIME command shall fail if: 20744 [EINVAL] Invalid arg value. | 20745 I_GETCLTIME This request returns the close time delay in the integer pointed to by arg. System Interfaces, Issue 6 1135 ioctl( ) System Interfaces 20746 Multiplexed STREAMS Configurations 20747 The following commands are used for connecting and disconnecting multiplexed STREAMS 20748 configurations. These commands use an implementation-defined default timeout interval. | 20749 I_LINK Connects two STREAMs, where fildes is the file descriptor of the STREAM 20750 connected to the multiplexing driver, and arg is the file descriptor of the 20751 STREAM connected to another driver. The STREAM designated by arg is 20752 connected below the multiplexing driver. I_LINK requires the multiplexing 20753 driver to send an acknowledgement message to the STREAM head regarding 20754 the connection. This call returns a multiplexer ID number (an identifier used 20755 to disconnect the multiplexer; see I_UNLINK) on success, and -1 on failure. 20756 The ioctl( ) function with the I_LINK command shall fail if: 20757 [ENXIO] Hangup received on fildes. | 20758 [ETIME] Timeout before acknowledgement message was received at | 20759 STREAM head. 20760 [EAGAIN] or [ENOSR] | 20761 Unable to allocate STREAMS storage to perform the 20762 I_LINK. 20763 [EBADF] The arg argument is not a valid, open file descriptor. | 20764 [EINVAL] The fildes argument does not support multiplexing; or arg is | 20765 not a STREAM or is already connected downstream from a 20766 multiplexer; or the specified I_LINK operation would 20767 connect the STREAM head in more than one place in the 20768 multiplexed STREAM. 20769 An I_LINK can also fail while waiting for the multiplexing driver to 20770 acknowledge the request, if a message indicating an error or a hangup is 20771 received at the STREAM head of fildes. In addition, an error code can be 20772 returned in the positive or negative acknowledgement message. For these 20773 cases, I_LINK fails with errno set to the value in the message. 20774 I_UNLINK Disconnects the two STREAMs specified by fildes and arg. fildes is the file 20775 descriptor of the STREAM connected to the multiplexing driver. The arg 20776 argument is the multiplexer ID number that was returned by the I_LINK 20777 ioctl( ) command when a STREAM was connected downstream from the 20778 multiplexing driver. If arg is MUXID_ALL, then all STREAMs that were 20779 connected to fildes are disconnected. As in I_LINK, this command requires 20780 acknowledgement. 20781 The ioctl( ) function with the I_UNLINK command shall fail if: 20782 [ENXIO] Hangup received on fildes. | 20783 [ETIME] Timeout before acknowledgement message was received at | 20784 STREAM head. 20785 [EAGAIN] or [ENOSR] | 20786 Unable to allocate buffers for the acknowledgement 20787 message. 20788 [EINVAL] Invalid multiplexer ID number. | 1136 Technical Standard (2000) (Draft July 31, 2000) System Interfaces ioctl( ) 20789 An I_UNLINK can also fail while waiting for the multiplexing driver to 20790 acknowledge the request if a message indicating an error or a hangup is 20791 received at the STREAM head of fildes. In addition, an error code can be 20792 returned in the positive or negative acknowledgement message. For these 20793 cases, I_UNLINK fails with errno set to the value in the message. 20794 I_PLINK Creates a persistent connection between two STREAMs, where fildes is the file 20795 descriptor of the STREAM connected to the multiplexing driver, and arg is the 20796 file descriptor of the STREAM connected to another driver. This call creates a 20797 persistent connection which can exist even if the file descriptor fildes 20798 associated with the upper STREAM to the multiplexing driver is closed. The 20799 STREAM designated by arg gets connected via a persistent connection below 20800 the multiplexing driver. I_PLINK requires the multiplexing driver to send an 20801 acknowledgement message to the STREAM head. This call returns a 20802 multiplexer ID number (an identifier that may be used to disconnect the 20803 multiplexer; see I_PUNLINK) on success, and -1 on failure. 20804 The ioctl( ) function with the I_PLINK command shall fail if: 20805 [ENXIO] Hangup received on fildes. | 20806 [ETIME] Timeout before acknowledgement message was received at | 20807 STREAM head. 20808 [EAGAIN] or [ENOSR] | 20809 Unable to allocate STREAMS storage to perform the 20810 I_PLINK. 20811 [EBADF] The arg argument is not a valid, open file descriptor. | 20812 [EINVAL] The fildes argument does not support multiplexing; or arg is | 20813 not a STREAM or is already connected downstream from a 20814 multiplexer; or the specified I_PLINK operation would 20815 connect the STREAM head in more than one place in the 20816 multiplexed STREAM. 20817 An I_PLINK can also fail while waiting for the multiplexing driver to 20818 acknowledge the request, if a message indicating an error or a hangup is 20819 received at the STREAM head of fildes. In addition, an error code can be 20820 returned in the positive or negative acknowledgement message. For these 20821 cases, I_PLINK fails with errno set to the value in the message. 20822 I_PUNLINK Disconnects the two STREAMs specified by fildes and arg from a persistent 20823 connection. The fildes argument is the file descriptor of the STREAM 20824 connected to the multiplexing driver. The arg argument is the multiplexer ID 20825 number that was returned by the I_PLINK ioctl( ) command when a STREAM 20826 was connected downstream from the multiplexing driver. If arg is 20827 MUXID_ALL, then all STREAMs which are persistent connections to fildes are 20828 disconnected. As in I_PLINK, this command requires the multiplexing driver 20829 to acknowledge the request. 20830 The ioctl( ) function with the I_PUNLINK command shall fail if: 20831 [ENXIO] Hangup received on fildes. | 20832 [ETIME] Timeout before acknowledgement message was received at | 20833 STREAM head. System Interfaces, Issue 6 1137 ioctl( ) System Interfaces 20834 [EAGAIN] or [ENOSR] | 20835 Unable to allocate buffers for the acknowledgement 20836 message. 20837 [EINVAL] Invalid multiplexer ID number. | 20838 An I_PUNLINK can also fail while waiting for the multiplexing driver to 20839 acknowledge the request if a message indicating an error or a hangup is 20840 received at the STREAM head of fildes. In addition, an error code can be 20841 returned in the positive or negative acknowledgement message. For these 20842 cases, I_PUNLINK fails with errno set to the value in the message. 20843 RETURN VALUE 20844 Upon successful completion, ioctl( ) shall return a value other than -1 that depends upon the 20845 STREAMS device control function. Otherwise, it shall return -1 and set errno to indicate the 20846 error. 20847 ERRORS 20848 Under the following general conditions, ioctl( ) shall fail if: 20849 [EBADF] The fildes argument is not a valid open file descriptor. | 20850 [EINTR] A signal was caught during the ioctl( ) operation. | 20851 [EINVAL] The STREAM or multiplexer referenced by fildes is linked (directly or | 20852 indirectly) downstream from a multiplexer. 20853 If an underlying device driver detects an error, then ioctl( ) shall fail if: 20854 [EINVAL] The request or arg argument is not valid for this device. | 20855 [EIO] Some physical I/O error has occurred. | 20856 [ENOTTY] The fildes argument is not associated with a STREAMS device that accepts | 20857 control functions. 20858 [ENXIO] The request and arg arguments are valid for this device driver, but the service | 20859 requested cannot be performed on this particular sub-device. 20860 [ENODEV] The fildes argument refers to a valid STREAMS device, but the corresponding | 20861 device driver does not support the ioctl( ) function. 20862 If a STREAM is connected downstream from a multiplexer, any ioctl( ) command except 20863 I_UNLINK and I_PUNLINK shall set errno to [EINVAL]. 20864 EXAMPLES 20865 None. 20866 APPLICATION USAGE 20867 The implementation-defined timeout interval for STREAMS has historically been 15 seconds. | 20868 RATIONALE 20869 None. 20870 FUTURE DIRECTIONS 20871 None. 20872 SEE ALSO 20873 close( ), fcntl( ), getmsg( ), open( ), pipe( ), poll( ), putmsg( ), read( ), sigaction( ), write( ), the Base | 20874 Definitions volume of IEEE Std. 1003.1-200x, , Section 2.6 (on page 539) | 1138 Technical Standard (2000) (Draft July 31, 2000) System Interfaces ioctl( ) 20875 CHANGE HISTORY 20876 First released in Issue 4, Version 2. 20877 Issue 5 20878 Moved from X/OPEN UNIX extension to BASE. 20879 Issue 6 20880 The Open Group corrigenda item U028/4 has been applied, correcting text in the I_FDINSERT, 20881 [EINVAL] case to refer to ctlbuf. 20882 This function is marked as part of the XSI STREAMS Option Group. 20883 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1139 isalnum( ) System Interfaces 20884 NAME 20885 isalnum - test for an alphanumeric character 20886 SYNOPSIS 20887 #include 20888 int isalnum(int c); 20889 DESCRIPTION 20890 CX The functionality described on this reference page is aligned with the ISO C standard. Any 20891 conflict between the requirements described here and the ISO C standard is unintentional. This 20892 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 20893 The isalnum( ) function tests whether c is a character of class alpha or digit in the program's | 20894 current locale; see the Base Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale. | 20895 In all cases c is an int, the value of which the application shall ensure is representable as an 20896 unsigned char or equal to the value of the macro EOF. If the argument has any other value, the 20897 behavior is undefined. 20898 RETURN VALUE 20899 The isalnum( ) function shall return non-zero if c is an alphanumeric character; otherwise, it shall 20900 return 0. 20901 ERRORS 20902 No errors are defined. 20903 EXAMPLES 20904 None. 20905 APPLICATION USAGE 20906 To ensure applications portability, especially across natural languages, only this function and 20907 those listed in the SEE ALSO section should be used for character classification. 20908 RATIONALE 20909 None. 20910 FUTURE DIRECTIONS 20911 None. 20912 SEE ALSO 20913 isalpha( ), iscntrl( ), isdigit( ), isgraph( ), islower( ), isprint( ), ispunct( ), isspace( ), isupper( ), isxdigit( ), 20914 setlocale( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , , the Base | 20915 Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale | 20916 CHANGE HISTORY 20917 First released in Issue 1. Derived from Issue 1 of the SVID. | 20918 Issue 4 20919 The text of the DESCRIPTION and RETURN VALUE sections is revised, although there are no 20920 functional differences between this issue and Issue 3. Operation in the C locale is no longer 20921 described explicitly on this reference page. 20922 Issue 6 20923 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 1140 Technical Standard (2000) (Draft July 31, 2000) System Interfaces isalpha( ) 20924 NAME 20925 isalpha - test for an alphabetic character 20926 SYNOPSIS 20927 #include 20928 int isalpha(int c); 20929 DESCRIPTION 20930 CX The functionality described on this reference page is aligned with the ISO C standard. Any 20931 conflict between the requirements described here and the ISO C standard is unintentional. This 20932 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 20933 The isalpha( ) function shall test whether c is a character of class alpha in the program's current | 20934 locale; see the Base Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale. | 20935 In all cases c is an int, the value of which the application shall ensure is representable as an 20936 unsigned char or equal to the value of the macro EOF. If the argument has any other value, the 20937 behavior is undefined. 20938 RETURN VALUE 20939 The isalpha( ) function shall return non-zero if c is an alphabetic character; otherwise, it shall 20940 return 0. 20941 ERRORS 20942 No errors are defined. 20943 EXAMPLES 20944 None. 20945 APPLICATION USAGE 20946 To ensure applications portability, especially across natural languages, only this function and 20947 those listed in the SEE ALSO section should be used for character classification. 20948 RATIONALE 20949 None. 20950 FUTURE DIRECTIONS 20951 None. 20952 SEE ALSO 20953 isalnum( ), iscntrl( ), isdigit( ), isgraph( ), islower( ), isprint( ), ispunct( ), isspace( ), isupper( ), 20954 isxdigit( ), setlocale( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , , | 20955 the Base Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale | 20956 CHANGE HISTORY 20957 First released in Issue 1. Derived from Issue 1 of the SVID. | 20958 Issue 4 20959 The text of the DESCRIPTION and RETURN VALUE sections is revised, although there are no 20960 functional differences between this issue and Issue 3. Operation in the C locale is no longer 20961 described explicitly on this reference page. 20962 Issue 6 20963 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1141 isascii( ) System Interfaces 20964 NAME 20965 isascii - test for a 7-bit US-ASCII character 20966 SYNOPSIS 20967 XSI #include 20968 int isascii(int c); 20969 20970 DESCRIPTION 20971 The isascii( ) function tests whether c is a 7-bit US-ASCII character code. 20972 The isascii( ) function is defined on all integer values. 20973 RETURN VALUE 20974 The isascii( ) function shall return non-zero if c is a 7-bit US-ASCII character code between 0 and 20975 octal 0177 inclusive; otherwise, it shall return 0. 20976 ERRORS 20977 No errors are defined. 20978 EXAMPLES 20979 None. 20980 APPLICATION USAGE 20981 None. 20982 RATIONALE 20983 None. 20984 FUTURE DIRECTIONS 20985 None. 20986 SEE ALSO 20987 The Base Definitions volume of IEEE Std. 1003.1-200x, | 20988 CHANGE HISTORY 20989 First released in Issue 1. Derived from Issue 1 of the SVID. | 1142 Technical Standard (2000) (Draft July 31, 2000) System Interfaces isastream( ) 20990 NAME 20991 isastream - test a file descriptor (STREAMS) 20992 SYNOPSIS 20993 XSR #include 20994 int isastream(int fildes); 20995 20996 DESCRIPTION 20997 The isastream( ) function shall test whether fildes, an open file descriptor, is associated with a 20998 STREAMS-based file. 20999 RETURN VALUE 21000 Upon successful completion, isastream( ) shall return 1 if fildes refers to a STREAMS-based file 21001 and 0 if not. Otherwise, isastream( ) shall return -1 and set errno to indicate the error. 21002 ERRORS 21003 The isastream( ) function shall fail if: 21004 [EBADF] The fildes argument is not a valid open file descriptor. | 21005 EXAMPLES 21006 None. 21007 APPLICATION USAGE 21008 None. 21009 RATIONALE 21010 None. 21011 FUTURE DIRECTIONS 21012 None. 21013 SEE ALSO 21014 The Base Definitions volume of IEEE Std. 1003.1-200x, | 21015 CHANGE HISTORY 21016 First released in Issue 4, Version 2. 21017 Issue 5 21018 Moved from X/OPEN UNIX extension to BASE. System Interfaces, Issue 6 1143 isatty( ) System Interfaces 21019 NAME 21020 isatty - test for a terminal device 21021 SYNOPSIS 21022 #include 21023 int isatty(int fildes); 21024 DESCRIPTION 21025 The isatty( ) function shall test whether fildes, an open file descriptor, is associated with a 21026 terminal device. 21027 RETURN VALUE 21028 The isatty( ) function shall return 1 if fildes is associated with a terminal; otherwise, it shall return | 21029 0 and may set errno to indicate the error. | 21030 ERRORS 21031 The isatty( ) function may fail if: 21032 [EBADF] The fildes argument is not a valid open file descriptor. | 21033 [ENOTTY] The fildes argument is not associated with a terminal. | 21034 EXAMPLES 21035 None. 21036 APPLICATION USAGE 21037 The isatty( ) function does not necessarily indicate that a human being is available for interaction 21038 via fildes. It is quite possible that non-terminal devices are connected to the communications 21039 line. 21040 RATIONALE 21041 None. 21042 FUTURE DIRECTIONS 21043 None. 21044 SEE ALSO 21045 The Base Definitions volume of IEEE Std. 1003.1-200x, | 21046 CHANGE HISTORY 21047 First released in Issue 1. Derived from Issue 1 of the SVID. | 21048 Issue 4 21049 The header is added to the SYNOPSIS section. 21050 In the RETURN VALUE section, the sentence indicating that this function may set errno is 21051 marked as an extension. 21052 The errors [EBADF] and [ENOTTY] are marked as extensions. 21053 Issue 6 21054 The following new requirements on POSIX implementations derive from alignment with the 21055 Single UNIX Specification: 21056 * The optional setting of errno to indicate an error is added. | 21057 * The [EBADF] and [ENOTTY] optional error conditions are added. 1144 Technical Standard (2000) (Draft July 31, 2000) System Interfaces isblank( ) 21058 NAME | 21059 isblank - test for a blank character | 21060 SYNOPSIS | 21061 #include | 21062 int isblank(int c); | 21063 DESCRIPTION | 21064 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 21065 conflict between the requirements described here and the ISO C standard is unintentional. This | 21066 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 21067 The isblank( ) function shall test whether c is a character of class blank in the program's current | 21068 locale; see the Base Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale. In all cases c | 21069 is a type int, the value of which the application shall ensure is a character representable as an | 21070 unsigned char or equal to the value of the macro EOF. If the argument has any other value, the | 21071 behavior is undefined. | 21072 RETURN VALUE | 21073 The isblank( ) function shall return non-zero if c is a character; otherwise, it shall return | 21074 0. | 21075 ERRORS | 21076 No errors are defined. | 21077 EXAMPLES | 21078 None. | 21079 APPLICATION USAGE | 21080 To ensure applications portability, especially across natural languages, only this function and | 21081 those listed in the SEE ALSO section should be used for character classification. | 21082 RATIONALE | 21083 None. | 21084 FUTURE DIRECTIONS | 21085 None. | 21086 SEE ALSO | 21087 isalnum( ), isalpha( ), iscntrl( ), isdigit( ), isgraph( ), islower( ), isprint( ), ispunct( ), isspace( ), isupper( ), | 21088 isxdigit( ), setlocale( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 21089 CHANGE HISTORY || 21090 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 1145 iscntrl( ) System Interfaces 21091 NAME 21092 iscntrl - test for a control character 21093 SYNOPSIS 21094 #include 21095 int iscntrl(int c); 21096 DESCRIPTION 21097 CX The functionality described on this reference page is aligned with the ISO C standard. Any 21098 conflict between the requirements described here and the ISO C standard is unintentional. This 21099 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 21100 The iscntrl( ) function shall test whether c is a character of class cntrl in the program's current | 21101 locale; see the Base Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale. | 21102 In all cases c is a type int, the value of which the application shall ensure is a character 21103 representable as an unsigned char or equal to the value of the macro EOF. If the argument has 21104 any other value, the behavior is undefined. 21105 RETURN VALUE 21106 The iscntrl( ) function shall return non-zero if c is a control character; otherwise, it shall return 0. 21107 ERRORS 21108 No errors are defined. 21109 EXAMPLES 21110 None. 21111 APPLICATION USAGE 21112 To ensure applications portability, especially across natural languages, only this function and 21113 those listed in the SEE ALSO section should be used for character classification. 21114 RATIONALE 21115 None. 21116 FUTURE DIRECTIONS 21117 None. 21118 SEE ALSO 21119 isalnum( ), isalpha( ), isdigit( ), isgraph( ), islower( ), isprint( ), ispunct( ), isspace( ), isupper( ), 21120 isxdigit( ), setlocale( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , the Base | 21121 Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale | 21122 CHANGE HISTORY 21123 First released in Issue 1. Derived from Issue 1 of the SVID. | 21124 Issue 4 21125 The text of the DESCRIPTION and RETURN VALUE sections is revised, although there are no 21126 functional differences between this issue and Issue 3. Operation in the C locale is no longer 21127 described explicitly on this reference page. 21128 Issue 6 21129 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 1146 Technical Standard (2000) (Draft July 31, 2000) System Interfaces isdigit( ) 21130 NAME 21131 isdigit - test for a decimal digit 21132 SYNOPSIS 21133 #include 21134 int isdigit(int c); 21135 DESCRIPTION 21136 CX The functionality described on this reference page is aligned with the ISO C standard. Any 21137 conflict between the requirements described here and the ISO C standard is unintentional. This 21138 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 21139 The isdigit( ) function shall test whether c is a character of class digit in the program's current | 21140 locale; see the Base Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale. | 21141 In all cases c is an int, the value of which the application shall ensure is a character representable 21142 as an unsigned char or equal to the value of the macro EOF. If the argument has any other value, 21143 the behavior is undefined. 21144 RETURN VALUE 21145 The isdigit( ) function shall return non-zero if c is a decimal digit; otherwise, it shall return 0. 21146 ERRORS 21147 No errors are defined. 21148 EXAMPLES 21149 None. 21150 APPLICATION USAGE 21151 To ensure applications portability, especially across natural languages, only this function and 21152 those listed in the SEE ALSO section should be used for character classification. 21153 RATIONALE 21154 None. 21155 FUTURE DIRECTIONS 21156 None. 21157 SEE ALSO 21158 isalnum( ), isalpha( ), iscntrl( ), isgraph( ), islower( ), isprint( ), ispunct( ), isspace( ), isupper( ), 21159 isxdigit( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 21160 CHANGE HISTORY 21161 First released in Issue 1. Derived from Issue 1 of the SVID. | 21162 Issue 4 21163 The text of the DESCRIPTION is revised, although there are no functional differences between 21164 this issue and Issue 3. 21165 Issue 6 21166 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1147 isfdtype( ) System Interfaces 21167 NAME 21168 isfdtype - determine whether a file descriptor refers to a socket 21169 SYNOPSIS 21170 #include 21171 int isfdtype(int fildes, int fdtype); 21172 DESCRIPTION 21173 The isfdtype( ) function shall determine whether the descriptor fildes has the properties identified 21174 by the value of fdtype, returning 1 if so, and 0 if not. 21175 If fdtype has the value S_IFSOCK: 21176 * The isfdtype( ) function shall return 1 if the descriptor refers to a socket. 21177 * It is implementation-defined whether isfdtype( ) shall return 1 if the descriptor refers to a | 21178 pipe. 21179 * The function shall return 0 for descriptors that refer neither to a socket nor to a pipe. 21180 RETURN VALUE 21181 Upon successful completion, the isfdtype( ) function shall return a value of 1 or 0 indicating 21182 whether the descriptor is of the indicated type. Otherwise, it shall return a value of -1 and set 21183 errno to indicate the error. 21184 ERRORS 21185 If any of the following conditions occur, the isfdtype( ) function shall return -1 and set errno to 21186 the corresponding value: 21187 [EBADF] The fildes argument is not a valid file descriptor. 21188 EXAMPLES 21189 None. 21190 APPLICATION USAGE 21191 None. 21192 RATIONALE 21193 None. 21194 FUTURE DIRECTIONS 21195 None. 21196 SEE ALSO 21197 isatty( ), socket( ), stat( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 21198 CHANGE HISTORY | 21199 First released in Issue 6. Derived from IEEE Std. 1003.1g-2000. | 1148 Technical Standard (2000) (Draft July 31, 2000) System Interfaces isfinite( ) 21200 NAME | 21201 isfinite - test for finite value | 21202 SYNOPSIS | 21203 #include | 21204 int isfinite(real-floating x); | 21205 DESCRIPTION | 21206 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 21207 conflict between the requirements described here and the ISO C standard is unintentional. This | 21208 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 21209 The isfinite( ) macro shall determine whether its argument has a finite value (zero, subnormal, or | 21210 normal, and not infinite or NaN). First, an argument represented in a format wider than its | 21211 semantic type is converted to its semantic type. Then determination is based on the type of the | 21212 argument. | 21213 RETURN VALUE | 21214 The isfinite( ) macro shall return a non-zero value if and only if its argument has a finite value. | 21215 ERRORS | 21216 No errors are defined. | 21217 EXAMPLES | 21218 None. | 21219 APPLICATION USAGE | 21220 None. | 21221 RATIONALE | 21222 None. | 21223 FUTURE DIRECTIONS | 21224 None. | 21225 SEE ALSO | 21226 fpclassify( ), isinf( ), isnan( ), isnormal( ), signbit( ), the Base Definitions volume of | 21227 IEEE Std. 1003.1-200x | 21228 CHANGE HISTORY || 21229 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 1149 isgraph( ) System Interfaces 21230 NAME 21231 isgraph - test for a visible character 21232 SYNOPSIS 21233 #include 21234 int isgraph(int c); 21235 DESCRIPTION 21236 CX The functionality described on this reference page is aligned with the ISO C standard. Any 21237 conflict between the requirements described here and the ISO C standard is unintentional. This 21238 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 21239 The isgraph( ) function shall test whether c is a character of class graph in the program's current | 21240 locale; see the Base Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale. | 21241 In all cases c is an int, the value of which the application shall ensure is a character representable 21242 as an unsigned char or equal to the value of the macro EOF. If the argument has any other value, 21243 the behavior is undefined. 21244 RETURN VALUE 21245 The isgraph( ) function shall return non-zero if c is a character with a visible representation; 21246 otherwise, it shall return 0. 21247 ERRORS 21248 No errors are defined. 21249 EXAMPLES 21250 None. 21251 APPLICATION USAGE 21252 To ensure applications portability, especially across natural languages, only this function and 21253 those listed in the SEE ALSO section should be used for character classification. 21254 RATIONALE 21255 None. 21256 FUTURE DIRECTIONS 21257 None. 21258 SEE ALSO 21259 isalnum( ), isalpha( ), iscntrl( ), isdigit( ), islower( ), isprint( ), ispunct( ), isspace( ), isupper( ), isxdigit( ), 21260 setlocale( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , the Base Definitions | 21261 volume of IEEE Std. 1003.1-200x, Chapter 7, Locale | 21262 CHANGE HISTORY 21263 First released in Issue 1. Derived from Issue 1 of the SVID. | 21264 Issue 4 21265 The text of the DESCRIPTION and RETURN VALUE sections is revised, although there are no 21266 functional differences between this issue and Issue 3. Operation in the C locale is no longer 21267 described explicitly on this reference page. 21268 Issue 6 | 21269 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 1150 Technical Standard (2000) (Draft July 31, 2000) System Interfaces isgreater( ) 21270 NAME | 21271 isgreater - test if x greater than y | 21272 SYNOPSIS | 21273 #include | 21274 int isgreater(real-floating x, real-floating y); | 21275 DESCRIPTION | 21276 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 21277 conflict between the requirements described here and the ISO C standard is unintentional. This | 21278 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 21279 The isgreater( ) macro shall determine whether its first argument is greater than its second | 21280 argument. The value of isgreater(x, y) shall be equal to (x) > (y); however, unlike (x) > (y), | 21281 isgreater(x, y) shall not raise the invalid floating-point exception when x and y are unordered. | 21282 RETURN VALUE | 21283 Upon successful completion, the isgreater( ) macro shall return the value of (x) > (y). | 21284 If x or y is NaN, 0 shall be returned. | 21285 ERRORS | 21286 No errors are defined. | 21287 EXAMPLES | 21288 None. | 21289 APPLICATION USAGE | 21290 The relational and equality operators support the usual mathematical relationships between | 21291 numeric values. For any ordered pair of numeric values, exactly one of the relationships (less, | 21292 greater, and equal) is true. Relational operators may raise the invalid floating-point exception | 21293 when argument values are NaNs. For a NaN and a numeric value, or for two NaNs, just the | 21294 unordered relationship is true. This macro is a quiet (non-floating-point exception raising) | 21295 version of a relational operator. It facilitates writing efficient code that accounts for NaNs | 21296 without suffering the invalid floating-point exception. In the SYNOPSIS section, real-floating | 21297 indicates that the argument shall be an expression of real-floating type. | 21298 RATIONALE | 21299 None. | 21300 FUTURE DIRECTIONS | 21301 None. | 21302 SEE ALSO | 21303 isgreaterequal( ), isless( ), islessequal( ), islessgreater( ), isunordered( ), the Base Definitions volume of | 21304 IEEE Std. 1003.1-200x | 21305 CHANGE HISTORY || 21306 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 1151 isgreaterequal( ) System Interfaces 21307 NAME | 21308 isgreaterequal - test if x greater than or equal to y | 21309 SYNOPSIS | 21310 #include | 21311 int isgreaterequal(real-floating x, real-floating y); | 21312 DESCRIPTION | 21313 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 21314 conflict between the requirements described here and the ISO C standard is unintentional. This | 21315 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 21316 The isgreaterequal( ) macro shall determine whether its first argument is greater than or equal to | 21317 its second argument. The value of isgreaterequal(x, y) shall be equal to (x) >= (y); however, unlike | 21318 (x) >= (y), isgreaterequal(x, y) shall not raise the invalid floating-point exception when x and y are | 21319 unordered. | 21320 RETURN VALUE | 21321 Upon successful completion, the isgreaterequal( ) macro shall return the value of (x) >= (y). | 21322 If x or y is NaN, 0 shall be returned. | 21323 ERRORS | 21324 No errors are defined. | 21325 EXAMPLES | 21326 None. | 21327 APPLICATION USAGE | 21328 The relational and equality operators support the usual mathematical relationships between | 21329 numeric values. For any ordered pair of numeric values, exactly one of the relationships (less, | 21330 greater, and equal) is true. Relational operators may raise the invalid floating-point exception | 21331 when argument values are NaNs. For a NaN and a numeric value, or for two NaNs, just the | 21332 unordered relationship is true. This macro is a quiet (non-floating-point exception raising) | 21333 version of a relational operator. It facilitates writing efficient code that accounts for NaNs | 21334 without suffering the invalid floating-point exception. In the SYNOPSIS section, real-floating | 21335 indicates that the argument shall be an expression of real-floating type. | 21336 RATIONALE | 21337 None. | 21338 FUTURE DIRECTIONS | 21339 None. | 21340 SEE ALSO | 21341 isgreater( ), isless( ), islessequal( ), islessgreater( ), isunordered( ), the Base Definitions volume of | 21342 IEEE Std. 1003.1-200x | 21343 CHANGE HISTORY || 21344 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | 1152 Technical Standard (2000) (Draft July 31, 2000) System Interfaces isinf( ) 21345 NAME | 21346 isinf - test for infinity | 21347 SYNOPSIS | 21348 #include | 21349 int isinf(real-floating x); | 21350 DESCRIPTION | 21351 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 21352 conflict between the requirements described here and the ISO C standard is unintentional. This | 21353 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 21354 The isinf( ) macro shall determine whether its argument value is an infinity (positive or | 21355 negative). First, an argument represented in a format wider than its semantic type is converted | 21356 to its semantic type. Then determination is based on the type of the argument. | 21357 RETURN VALUE | 21358 The isinf( ) macro shall return a non-zero value if and only if its argument has an infinite value. | 21359 ERRORS | 21360 No errors are defined. | 21361 EXAMPLES | 21362 None. | 21363 APPLICATION USAGE | 21364 None. | 21365 RATIONALE | 21366 None. | 21367 FUTURE DIRECTIONS | 21368 None. | 21369 SEE ALSO | 21370 fpclassify( ), isfinite( ), isnan( ), isnormal( ), signbit( ), the Base Definitions volume of | 21371 IEEE Std. 1003.1-200x | 21372 CHANGE HISTORY || 21373 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 1153 isless( ) System Interfaces 21374 NAME | 21375 isless - test if x is less than y | 21376 SYNOPSIS | 21377 #include | 21378 int isless(real-floating x, real-floating y); | 21379 DESCRIPTION | 21380 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 21381 conflict between the requirements described here and the ISO C standard is unintentional. This | 21382 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 21383 The isless( ) macro shall determine whether its first argument is less than its second argument. | 21384 The value of isless(x, y) shall be equal to (x) < (y); however, unlike (x) < (y), isless(x, y) shall not | 21385 raise the invalid floating-point exception when x and y are unordered. | 21386 RETURN VALUE | 21387 Upon successful completion, the isless( ) macro shall return the value of (x) < (y). | 21388 If x or y is NaN, 0 shall be returned. | 21389 ERRORS | 21390 No errors are defined. | 21391 EXAMPLES | 21392 None. | 21393 APPLICATION USAGE | 21394 The relational and equality operators support the usual mathematical relationships between | 21395 numeric values. For any ordered pair of numeric values, exactly one of the relationships (less, | 21396 greater, and equal) is true. Relational operators may raise the invalid floating-point exception | 21397 when argument values are NaNs. For a NaN and a numeric value, or for two NaNs, just the | 21398 unordered relationship is true. This macro is a quiet (non-floating-point exception raising) | 21399 version of a relational operator. It facilitates writing efficient code that accounts for NaNs | 21400 without suffering the invalid floating-point exception. In the SYNOPSIS section, real-floating | 21401 indicates that the argument shall be an expression of real-floating type. | 21402 RATIONALE | 21403 None. | 21404 FUTURE DIRECTIONS | 21405 None. | 21406 SEE ALSO | 21407 isgreater( ), isgreaterequal( ), islessequal( ), islessgreater( ), isunordered( ), the Base Definitions volume | 21408 of IEEE Std. 1003.1-200x, | 21409 CHANGE HISTORY || 21410 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | 1154 Technical Standard (2000) (Draft July 31, 2000) System Interfaces islessequal( ) 21411 NAME | 21412 islessequal - test if x is less than or equal to y | 21413 SYNOPSIS | 21414 #include | 21415 int islessequal(real-floating x, real-floating y); | 21416 DESCRIPTION | 21417 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 21418 conflict between the requirements described here and the ISO C standard is unintentional. This | 21419 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 21420 The islessequal( ) macro shall determine whether its first argument is less than or equal to its | 21421 second argument. The value of islessequal(x, y) shall be equal to (x) <= (y); however, unlike | 21422 (x) <= (y), islessequal(x, y) shall not raise the invalid floating-point exception when x and y are | 21423 unordered. | 21424 RETURN VALUE | 21425 Upon successful completion, the islessequal( ) macro shall return the value of (x) <= (y). | 21426 If x or y is NaN, 0 shall be returned. | 21427 ERRORS | 21428 No errors are defined. | 21429 EXAMPLES | 21430 None. | 21431 APPLICATION USAGE | 21432 The relational and equality operators support the usual mathematical relationships between | 21433 numeric values. For any ordered pair of numeric values, exactly one of the relationships (less, | 21434 greater, and equal) is true. Relational operators may raise the invalid floating-point exception | 21435 when argument values are NaNs. For a NaN and a numeric value, or for two NaNs, just the | 21436 unordered relationship is true. This macro is a quiet (non-floating-point exception raising) | 21437 version of a relational operator. It facilitates writing efficient code that accounts for NaNs | 21438 without suffering the invalid floating-point exception. In the SYNOPSIS section, real-floating | 21439 indicates that the argument shall be an expression of real-floating type. | 21440 RATIONALE | 21441 None. | 21442 FUTURE DIRECTIONS | 21443 None. | 21444 SEE ALSO | 21445 isgreater( ), isgreaterequal( ), isless( ), islessgreater( ), isunordered( ), the Base Definitions volume of | 21446 IEEE Std. 1003.1-200x | 21447 CHANGE HISTORY || 21448 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 1155 islessgreater( ) System Interfaces 21449 NAME | 21450 islessgreater - test if x is less than or greater than y | 21451 SYNOPSIS | 21452 #include | 21453 int islessgreater(real-floating x, real-floating y); | 21454 DESCRIPTION | 21455 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 21456 conflict between the requirements described here and the ISO C standard is unintentional. This | 21457 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 21458 The islessgreater( ) macro shall determine whether its first argument is less than or greater than | 21459 its second argument. The islessgreater(x, y) macro is similar to (x) < (y) || (x) > (y); however, | 21460 islessgreater(x, y) shall not raise the invalid floating-point exception when x and y are unordered | 21461 (nor shall it evaluate x and y twice). | 21462 RETURN VALUE | 21463 Upon successful completion, the islessgreater( ) macro shall return the value of | 21464 (x) < (y) || (x) > (y). | 21465 If x or y is NaN, 0 shall be returned. | 21466 ERRORS | 21467 No errors are defined. | 21468 EXAMPLES | 21469 None. | 21470 APPLICATION USAGE | 21471 The relational and equality operators support the usual mathematical relationships between | 21472 numeric values. For any ordered pair of numeric values, exactly one of the relationships (less, | 21473 greater, and equal) is true. Relational operators may raise the invalid floating-point exception | 21474 when argument values are NaNs. For a NaN and a numeric value, or for two NaNs, just the | 21475 unordered relationship is true. This macro is a quiet (non-floating-point exception raising) | 21476 version of a relational operator. It facilitates writing efficient code that accounts for NaNs | 21477 without suffering the invalid floating-point exception. In the SYNOPSIS section, real-floating | 21478 indicates that the argument shall be an expression of real-floating type. | 21479 RATIONALE | 21480 None. | 21481 FUTURE DIRECTIONS | 21482 None. | 21483 SEE ALSO | 21484 isgreater( ), isgreaterequal( ), isless( ), islessequal( ), isunordered( ), the Base Definitions volume of | 21485 IEEE Std. 1003.1-200x | 21486 CHANGE HISTORY || 21487 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | 1156 Technical Standard (2000) (Draft July 31, 2000) System Interfaces islower( ) 21488 NAME 21489 islower - test for a lowercase letter 21490 SYNOPSIS 21491 #include 21492 int islower(int c); 21493 DESCRIPTION 21494 CX The functionality described on this reference page is aligned with the ISO C standard. Any 21495 conflict between the requirements described here and the ISO C standard is unintentional. This 21496 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 21497 The islower( ) function shall test whether c is a character of class lower in the program's current | 21498 locale; see the Base Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale. | 21499 In all cases c is an int, the value of which the application shall ensure is a character representable 21500 as an unsigned char or equal to the value of the macro EOF. If the argument has any other value, 21501 the behavior is undefined. 21502 RETURN VALUE 21503 The islower( ) function shall return non-zero if c is a lowercase letter; otherwise, it shall return 0. 21504 ERRORS 21505 No errors are defined. 21506 EXAMPLES 21507 Testing for a Lowercase Letter 21508 The following example tests whether the value is a lowercase letter, based on the locale of the 21509 user, then uses it as part of a key value. 21510 #include 21511 #include 21512 #include 21513 ... 21514 char *keystr; 21515 int elementlen, len; 21516 char c; 21517 ... 21518 setlocale(LC_ALL, ""); 21519 ... 21520 len = 0; 21521 while (len < elementlen) { 21522 c = (char) (rand() % 256); 21523 ... 21524 if (islower(c)) 21525 keystr[len++] = c; 21526 } 21527 ... 21528 APPLICATION USAGE 21529 To ensure applications portability, especially across natural languages, only this function and 21530 those listed in the SEE ALSO section should be used for character classification. System Interfaces, Issue 6 1157 islower( ) System Interfaces 21531 RATIONALE 21532 None. 21533 FUTURE DIRECTIONS 21534 None. 21535 SEE ALSO 21536 isalnum( ), isalpha( ), iscntrl( ), isdigit( ), isgraph( ), isprint( ), ispunct( ), isspace( ), isupper( ), 21537 isxdigit( ), setlocale( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , the Base | 21538 Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale | 21539 CHANGE HISTORY 21540 First released in Issue 1. Derived from Issue 1 of the SVID. | 21541 Issue 4 21542 The text of the DESCRIPTION and RETURN VALUE sections is revised, although there are no 21543 functional differences between this issue and Issue 3. Operation in the C locale is no longer 21544 described explicitly on this reference page. 21545 Issue 6 21546 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 1158 Technical Standard (2000) (Draft July 31, 2000) System Interfaces isnan( ) 21547 NAME 21548 isnan - test for a NaN 21549 SYNOPSIS 21550 #include | 21551 int isnan(real-floating x); | 21552 DESCRIPTION | 21553 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 21554 conflict between the requirements described here and the ISO C standard is unintentional. This | 21555 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 21556 The isnan( ) macro shall determine whether its argument value is a NaN. First, an argument | 21557 represented in a format wider than its semantic type is converted to its semantic type. Then | 21558 determination is based on the type of the argument. | 21559 RETURN VALUE 21560 The isnan( ) macro shall return a non-zero value if and only if its argument has a NaN value. | 21561 ERRORS 21562 No errors are defined. 21563 EXAMPLES 21564 None. 21565 APPLICATION USAGE 21566 None. 21567 RATIONALE 21568 None. 21569 FUTURE DIRECTIONS 21570 None. 21571 SEE ALSO 21572 fpclassify( ), isfinite( ), isinf( ), isnormal( ), signbit( ), the Base Definitions volume of | 21573 IEEE Std. 1003.1-200x, | 21574 CHANGE HISTORY 21575 First released in Issue 3. 21576 Issue 4 21577 The words ``not supporting NaN'' are added to the APPLICATION USAGE section. 21578 Issue 5 21579 The DESCRIPTION is updated to indicate the return value when NaN is not supported. This | 21580 text was previously published in the APPLICATION USAGE section. | 21581 Issue 6 || 21582 Entry re-written for alignment with the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 1159 isnormal( ) System Interfaces 21583 NAME | 21584 isnormal - test for a normal value | 21585 SYNOPSIS | 21586 #include | 21587 int isnormal(real-floating x); | 21588 DESCRIPTION | 21589 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 21590 conflict between the requirements described here and the ISO C standard is unintentional. This | 21591 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 21592 The isnormal( ) macro shall determine whether its argument value is normal (neither zero, | 21593 subnormal, infinite, nor NaN). First, an argument represented in a format wider than its | 21594 semantic type is converted to its semantic type. Then determination is based on the type of the | 21595 argument. | 21596 RETURN VALUE | 21597 The isnormal( ) macro shall return a non-zero value if and only if its argument has a normal | 21598 value. | 21599 ERRORS | 21600 No errors are defined. | 21601 EXAMPLES | 21602 None. | 21603 APPLICATION USAGE | 21604 None. | 21605 RATIONALE | 21606 None. | 21607 FUTURE DIRECTIONS | 21608 None. | 21609 SEE ALSO | 21610 fpclassify( ), isfinite( ), isinf( ), isnan( ), signbit( ), the Base Definitions volume of | 21611 IEEE Std. 1003.1-200x, | 21612 CHANGE HISTORY || 21613 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | 1160 Technical Standard (2000) (Draft July 31, 2000) System Interfaces isprint( ) 21614 NAME 21615 isprint - test for a printing character 21616 SYNOPSIS 21617 #include 21618 int isprint(int c); 21619 DESCRIPTION 21620 CX The functionality described on this reference page is aligned with the ISO C standard. Any 21621 conflict between the requirements described here and the ISO C standard is unintentional. This 21622 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 21623 The isprint( ) function shall test whether c is a character of class print in the program's current | 21624 locale; see the Base Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale. | 21625 In all cases c is an int, the value of which the application shall ensure is a character representable 21626 as an unsigned char or equal to the value of the macro EOF. If the argument has any other value, 21627 the behavior is undefined. 21628 RETURN VALUE 21629 The isprint( ) function shall return non-zero if c is a printing character; otherwise, it shall return 0. 21630 ERRORS 21631 No errors are defined. 21632 EXAMPLES 21633 None. 21634 APPLICATION USAGE 21635 To ensure applications portability, especially across natural languages, only this function and 21636 those listed in the SEE ALSO section should be used for character classification. 21637 RATIONALE 21638 None. 21639 FUTURE DIRECTIONS 21640 None. 21641 SEE ALSO 21642 isalnum( ), isalpha( ), iscntrl( ), isdigit( ), isgraph( ), islower( ), ispunct( ), isspace( ), isupper( ), 21643 isxdigit( ), setlocale( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , the Base | 21644 Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale | 21645 CHANGE HISTORY 21646 First released in Issue 1. Derived from Issue 1 of the SVID. | 21647 Issue 4 21648 The text of the DESCRIPTION and RETURN VALUE sections is revised, although there are no 21649 functional differences between this issue and Issue 3. Operation in the C locale is no longer 21650 described explicitly on this reference page. 21651 Issue 6 21652 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1161 ispunct( ) System Interfaces 21653 NAME 21654 ispunct - test for a punctuation character 21655 SYNOPSIS 21656 #include 21657 int ispunct(int c); 21658 DESCRIPTION 21659 CX The functionality described on this reference page is aligned with the ISO C standard. Any 21660 conflict between the requirements described here and the ISO C standard is unintentional. This 21661 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 21662 The ispunct( ) function shall test whether c is a character of class punct in the program's current | 21663 locale; see the Base Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale. | 21664 In all cases c is an int, the value of which the application shall ensure is a character representable 21665 as an unsigned char or equal to the value of the macro EOF. If the argument has any other value, 21666 the behavior is undefined. 21667 RETURN VALUE 21668 The ispunct( ) function shall return non-zero if c is a punctuation character; otherwise, it shall 21669 return 0. 21670 ERRORS 21671 No errors are defined. 21672 EXAMPLES 21673 None. 21674 APPLICATION USAGE 21675 To ensure applications portability, especially across natural languages, only this function and 21676 those listed in the SEE ALSO section should be used for character classification. 21677 RATIONALE 21678 None. 21679 FUTURE DIRECTIONS 21680 None. 21681 SEE ALSO 21682 isalnum( ), isalpha( ), iscntrl( ), isdigit( ), isgraph( ), islower( ), isprint( ), isspace( ), isupper( ), isxdigit( ), 21683 setlocale( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , the Base Definitions | 21684 volume of IEEE Std. 1003.1-200x, Chapter 7, Locale | 21685 CHANGE HISTORY 21686 First released in Issue 1. Derived from Issue 1 of the SVID. | 21687 Issue 4 21688 The text of the DESCRIPTION and RETURN VALUE sections is revised, although there are no 21689 functional differences between this issue and Issue 3. Operation in the C locale is no longer 21690 described explicitly on this reference page. 21691 Issue 6 21692 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 1162 Technical Standard (2000) (Draft July 31, 2000) System Interfaces isspace( ) 21693 NAME 21694 isspace - test for a white-space character 21695 SYNOPSIS 21696 #include 21697 int isspace(int c); 21698 DESCRIPTION 21699 CX The functionality described on this reference page is aligned with the ISO C standard. Any 21700 conflict between the requirements described here and the ISO C standard is unintentional. This 21701 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 21702 The isspace( ) function shall test whether c is a character of class space in the program's current | 21703 locale; see the Base Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale. | 21704 In all cases c is an int, the value of which the application shall ensure is a character representable 21705 as an unsigned char or equal to the value of the macro EOF. If the argument has any other value, 21706 the behavior is undefined. 21707 RETURN VALUE 21708 The isspace( ) function shall return non-zero if c is a white-space character; otherwise, it shall 21709 return 0. 21710 ERRORS 21711 No errors are defined. 21712 EXAMPLES 21713 None. 21714 APPLICATION USAGE 21715 To ensure applications portability, especially across natural languages, only this function and 21716 those listed in the SEE ALSO section should be used for character classification. 21717 RATIONALE 21718 None. 21719 FUTURE DIRECTIONS 21720 None. 21721 SEE ALSO 21722 isalnum( ), isalpha( ), iscntrl( ), isdigit( ), isgraph( ), islower( ), isprint( ), ispunct( ), isupper( ), 21723 isxdigit( ), setlocale( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , the Base | 21724 Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale | 21725 CHANGE HISTORY 21726 First released in Issue 1. Derived from Issue 1 of the SVID. | 21727 Issue 4 21728 The text of the DESCRIPTION and RETURN VALUE sections is revised, although there are no 21729 functional differences between this issue and Issue 3. Operation in the C locale is no longer 21730 described explicitly on this reference page. 21731 Issue 6 | 21732 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1163 isunordered( ) System Interfaces 21733 NAME | 21734 isunordered - test if arguments are unordered | 21735 SYNOPSIS | 21736 #include | 21737 int isunordered(real-floating x, real-floating y); | 21738 DESCRIPTION | 21739 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 21740 conflict between the requirements described here and the ISO C standard is unintentional. This | 21741 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 21742 The isunordered( ) macro shall determine whether its arguments are unordered. | 21743 RETURN VALUE | 21744 Upon successful completion, the isunordered( ) macro shall return 1 if its arguments are | 21745 unordered, and 0 otherwise. | 21746 If x or y is NaN, 0 shall be returned. | 21747 ERRORS | 21748 No errors are defined. | 21749 EXAMPLES | 21750 None. | 21751 APPLICATION USAGE | 21752 The relational and equality operators support the usual mathematical relationships between | 21753 numeric values. For any ordered pair of numeric values, exactly one of the relationships (less, | 21754 greater, and equal) is true. Relational operators may raise the invalid floating-point exception | 21755 when argument values are NaNs. For a NaN and a numeric value, or for two NaNs, just the | 21756 unordered relationship is true. This macro is a quiet (non-floating-point exception raising) | 21757 version of a relational operator. It facilitates writing efficient code that accounts for NaNs | 21758 without suffering the invalid floating-point exception. In the SYNOPSIS section, real-floating | 21759 indicates that the argument shall be an expression of real-floating type. | 21760 RATIONALE | 21761 None. | 21762 FUTURE DIRECTIONS | 21763 None. | 21764 SEE ALSO | 21765 isgreater( ), isgreaterequal( ), isless( ), islessequal( ), islessgreater( ), the Base Definitions volume of | 21766 IEEE Std. 1003.1-200x, | 21767 CHANGE HISTORY || 21768 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | 1164 Technical Standard (2000) (Draft July 31, 2000) System Interfaces isupper( ) 21769 NAME 21770 isupper - test for an uppercase letter 21771 SYNOPSIS 21772 #include 21773 int isupper(int c); 21774 DESCRIPTION 21775 CX The functionality described on this reference page is aligned with the ISO C standard. Any 21776 conflict between the requirements described here and the ISO C standard is unintentional. This 21777 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 21778 The isupper( ) function shall test whether c is a character of class upper in the program's current | 21779 locale; see the Base Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale. | 21780 In all cases c is an int, the value of which the application shall ensure is a character representable 21781 as an unsigned char or equal to the value of the macro EOF. If the argument has any other value, 21782 the behavior is undefined. 21783 RETURN VALUE 21784 The isupper( ) function shall return non-zero if c is an uppercase letter; otherwise, it shall return 0. 21785 ERRORS 21786 No errors are defined. 21787 EXAMPLES 21788 None. 21789 APPLICATION USAGE 21790 To ensure applications portability, especially across natural languages, only this function and 21791 those listed in the SEE ALSO section should be used for character classification. 21792 RATIONALE 21793 None. 21794 FUTURE DIRECTIONS 21795 None. 21796 SEE ALSO 21797 isalnum( ), isalpha( ), iscntrl( ), isdigit( ), isgraph( ), islower( ), isprint( ), ispunct( ), isspace( ), isxdigit( ), 21798 setlocale( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , the Base Definitions | 21799 volume of IEEE Std. 1003.1-200x, Chapter 7, Locale | 21800 CHANGE HISTORY 21801 First released in Issue 1. Derived from Issue 1 of the SVID. | 21802 Issue 4 21803 The text of the DESCRIPTION and RETURN VALUE sections is revised, although there are no 21804 functional differences between this issue and Issue 3. Operation in the C locale is no longer 21805 described explicitly on this reference page. 21806 Issue 6 21807 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1165 iswalnum( ) System Interfaces 21808 NAME 21809 iswalnum - test for an alphanumeric wide-character code 21810 SYNOPSIS 21811 #include 21812 int iswalnum(wint_t wc); 21813 DESCRIPTION 21814 CX The functionality described on this reference page is aligned with the ISO C standard. Any 21815 conflict between the requirements described here and the ISO C standard is unintentional. This 21816 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 21817 The iswalnum( ) function shall test whether wc is a wide-character code representing a character 21818 of class alpha or digit in the program's current locale; see the Base Definitions volume of | 21819 IEEE Std. 1003.1-200x, Chapter 7, Locale. | 21820 In all cases wc is a wint_t, the value of which the application shall ensure is a wide-character 21821 code corresponding to a valid character in the current locale, or equal to the value of the macro 21822 WEOF. If the argument has any other value, the behavior is undefined. 21823 RETURN VALUE 21824 The iswalnum( ) function shall return non-zero if wc is an alphanumeric wide-character code; 21825 otherwise, it shall return 0. 21826 ERRORS 21827 No errors are defined. 21828 EXAMPLES 21829 None. 21830 APPLICATION USAGE 21831 To ensure applications portability, especially across natural languages, only this function and 21832 those listed in the SEE ALSO section should be used for classification of wide-character codes. 21833 RATIONALE 21834 None. 21835 FUTURE DIRECTIONS 21836 None. 21837 SEE ALSO 21838 iswalpha( ), iswcntrl( ), iswctype( ), iswdigit( ), iswgraph( ), iswlower( ), iswprint( ), iswpunct( ), 21839 iswspace( ), iswupper( ), iswxdigit( ), setlocale( ), the Base Definitions volume of | 21840 IEEE Std. 1003.1-200x, , , , the Base Definitions volume of | 21841 IEEE Std. 1003.1-200x, Chapter 7, Locale | 21842 CHANGE HISTORY 21843 First released as a World-wide Portability Interface in Issue 4. 21844 Issue 5 21845 The following change has been made in this issue for alignment with 21846 ISO/IEC 9899: 1990/Amendment 1: 1995 (E): 21847 * The SYNOPSIS has been changed to indicate that this function and associated data types are 21848 now made visible by inclusion of the header rather than . 1166 Technical Standard (2000) (Draft July 31, 2000) System Interfaces iswalnum( ) 21849 Issue 6 21850 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1167 iswalpha( ) System Interfaces 21851 NAME 21852 iswalpha - test for an alphabetic wide-character code 21853 SYNOPSIS 21854 #include 21855 int iswalpha(wint_t wc); 21856 DESCRIPTION 21857 CX The functionality described on this reference page is aligned with the ISO C standard. Any 21858 conflict between the requirements described here and the ISO C standard is unintentional. This 21859 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 21860 The iswalpha( ) function shall test whether wc is a wide-character code representing a character of 21861 class alpha in the program's current locale; see the Base Definitions volume of | 21862 IEEE Std. 1003.1-200x, Chapter 7, Locale. | 21863 In all cases wc is a wint_t, the value of which the application shall ensure is a wide-character 21864 code corresponding to a valid character in the current locale, or equal to the value of the macro 21865 WEOF. If the argument has any other value, the behavior is undefined. 21866 RETURN VALUE 21867 The iswalpha( ) function shall return non-zero if wc is an alphabetic wide-character code; 21868 otherwise, it shall return 0. 21869 ERRORS 21870 No errors are defined. 21871 EXAMPLES 21872 None. 21873 APPLICATION USAGE 21874 To ensure applications portability, especially across natural languages, only this function and 21875 those listed in the SEE ALSO section should be used for classification of wide-character codes. 21876 RATIONALE 21877 None. 21878 FUTURE DIRECTIONS 21879 None. 21880 SEE ALSO 21881 iswalnum( ), iswcntrl( ), iswctype( ), iswdigit( ), iswgraph( ), iswlower( ), iswprint( ), iswpunct( ), 21882 iswspace( ), iswupper( ), iswxdigit( ), setlocale( ), the Base Definitions volume of | 21883 IEEE Std. 1003.1-200x, , , , the Base Definitions volume of | 21884 IEEE Std. 1003.1-200x, Chapter 7, Locale | 21885 CHANGE HISTORY 21886 First released in Issue 4. 21887 Issue 5 21888 The following change has been made in this issue for alignment with 21889 ISO/IEC 9899: 1990/Amendment 1: 1995 (E): 21890 * The SYNOPSIS has been changed to indicate that this function and associated data types are 21891 now made visible by inclusion of the header rather than . 1168 Technical Standard (2000) (Draft July 31, 2000) System Interfaces iswalpha( ) 21892 Issue 6 | 21893 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1169 iswblank( ) System Interfaces 21894 NAME | 21895 iswblank - test for a blank wide-character code | 21896 SYNOPSIS | 21897 #include | 21898 int iswblank(wint_t wc); | 21899 DESCRIPTION | 21900 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 21901 conflict between the requirements described here and the ISO C standard is unintentional. This | 21902 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 21903 The iswblank( ) function shall test whether wc is a wide-character code representing a character of | 21904 class blank in the program's current locale; see the Base Definitions volume of | 21905 IEEE Std. 1003.1-200x, Chapter 7, Locale. In all cases, wc is a wint_t, the value of which the | 21906 application shall ensure is a wide-character code corresponding to a valid character in the | 21907 current locale, or equal to the value of the macro WEOF. If the argument has any other value, the | 21908 behavior is undefined. | 21909 RETURN VALUE | 21910 The iswblank( ) function shall return non-zero if wc is a wide-character code; otherwise, | 21911 it shall return 0. | 21912 ERRORS | 21913 No errors are defined. | 21914 EXAMPLES | 21915 None. | 21916 APPLICATION USAGE | 21917 To ensure applications portability, especially across natural languages, only this function and | 21918 those listed in the SEE ALSO section should be used for classification of wide-character codes. | 21919 RATIONALE | 21920 None. | 21921 FUTURE DIRECTIONS | 21922 None. | 21923 SEE ALSO | 21924 iswalnum( ), iswalpha( ), iswcntrl( ), iswctype( ), iswdigit( ), iswgraph( ), iswlower( ), iswprint( ), | 21925 iswpunct( ), iswspace( ), iswupper( ), iswxdigit( ), setlocale( ), the Base Definitions volume of | 21926 IEEE Std. 1003.1-200x, , , | 21927 CHANGE HISTORY || 21928 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | 1170 Technical Standard (2000) (Draft July 31, 2000) System Interfaces iswcntrl( ) 21929 NAME 21930 iswcntrl - test for a control wide-character code 21931 SYNOPSIS 21932 #include 21933 int iswcntrl(wint_t wc); 21934 DESCRIPTION 21935 CX The functionality described on this reference page is aligned with the ISO C standard. Any 21936 conflict between the requirements described here and the ISO C standard is unintentional. This 21937 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 21938 The iswcntrl( ) function shall test whether wc is a wide-character code representing a character of 21939 class control in the program's current locale; see the Base Definitions volume of | 21940 IEEE Std. 1003.1-200x, Chapter 7, Locale. | 21941 In all cases wc is a wint_t, the value of which the application shall ensure is a wide-character 21942 code corresponding to a valid character in the current locale, or equal to the value of the macro 21943 WEOF. If the argument has any other value, the behavior is undefined. 21944 RETURN VALUE 21945 The iswcntrl( ) function shall return non-zero if wc is a control wide-character code; otherwise, it 21946 shall return 0. 21947 ERRORS 21948 No errors are defined. 21949 EXAMPLES 21950 None. 21951 APPLICATION USAGE 21952 To ensure applications portability, especially across natural languages, only this function and 21953 those listed in the SEE ALSO section should be used for classification of wide-character codes. 21954 RATIONALE 21955 None. 21956 FUTURE DIRECTIONS 21957 None. 21958 SEE ALSO 21959 iswalnum( ), iswalpha( ), iswctype( ), iswdigit( ), iswgraph( ), iswlower( ), iswprint( ), iswpunct( ), 21960 iswspace( ), iswupper( ), iswxdigit( ), setlocale( ), the Base Definitions volume of | 21961 IEEE Std. 1003.1-200x, , , the Base Definitions volume of | 21962 IEEE Std. 1003.1-200x, Chapter 7, Locale | 21963 CHANGE HISTORY 21964 First released in Issue 4. 21965 Issue 5 21966 The following change has been made in this issue for alignment with 21967 ISO/IEC 9899: 1990/Amendment 1: 1995 (E): 21968 * The SYNOPSIS has been changed to indicate that this function and associated data types are 21969 now made visible by inclusion of the header rather than . System Interfaces, Issue 6 1171 iswcntrl( ) System Interfaces 21970 Issue 6 21971 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 1172 Technical Standard (2000) (Draft July 31, 2000) System Interfaces iswctype( ) 21972 NAME 21973 iswctype - test character for a specified class 21974 SYNOPSIS 21975 #include 21976 int iswctype(wint_t wc, wctype_t charclass); 21977 DESCRIPTION 21978 CX The functionality described on this reference page is aligned with the ISO C standard. Any 21979 conflict between the requirements described here and the ISO C standard is unintentional. This 21980 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 21981 The iswctype( ) function shall determine whether the wide-character code wc has the character 21982 class charclass, returning true or false. The iswctype( ) function is defined on WEOF and wide- 21983 character codes corresponding to the valid character encodings in the current locale. If the wc | 21984 argument is not in the domain of the function, the result is undefined. If the value of charclass is | 21985 invalid (that is, not obtained by a call to wctype( ) or charclass is invalidated by a subsequent call 21986 to setlocale( ) that has affected category LC_CTYPE) the result is unspecified. | 21987 RETURN VALUE 21988 The iswctype( ) function shall return non-zero (true) if and only if wc has the property described | 21989 CX by charclass. If charclass is 0, iswctype( ) shall return 0. | 21990 ERRORS 21991 No errors are defined. 21992 EXAMPLES 21993 Testing for a Valid Character 21994 #include 21995 ... 21996 int yes_or_no; 21997 wint_t wc; 21998 wctype_t valid_class; 21999 ... 22000 if ((valid_class=wctype("vowel")) == (wctype_t)0) 22001 /* Invalid character class. */ 22002 yes_or_no=iswctype(wc,valid_class); 22003 APPLICATION USAGE 22004 The twelve strings "alnum", "alpha", "blank", "cntrl", "digit", "graph", "lower", 22005 "print", "punct", "space", "upper", and "xdigit" are reserved for the standard 22006 character classes. In the table below, the functions in the left column are equivalent to the 22007 functions in the right column. 22008 iswalnum(wc) iswctype(wc, wctype("alnum")) 22009 iswalpha(wc) iswctype(wc, wctype("alpha")) 22010 iswblank(wc) iswctype(wc, wctype("blank")) 22011 iswcntrl(wc) iswctype(wc, wctype("cntrl")) 22012 iswdigit(wc) iswctype(wc, wctype("digit")) 22013 iswgraph(wc) iswctype(wc, wctype("graph")) 22014 iswlower(wc) iswctype(wc, wctype("lower")) 22015 iswprint(wc) iswctype(wc, wctype("print")) 22016 iswpunct(wc) iswctype(wc, wctype("punct")) 22017 iswspace(wc) iswctype(wc, wctype("space")) System Interfaces, Issue 6 1173 iswctype( ) System Interfaces 22018 iswupper(wc) iswctype(wc, wctype("upper")) 22019 iswxdigit(wc) iswctype(wc, wctype("xdigit")) 22020 RATIONALE | 22021 None. 22022 FUTURE DIRECTIONS 22023 None. 22024 SEE ALSO 22025 iswalnum( ), iswalpha( ), iswcntrl( ), iswdigit( ), iswgraph( ), iswlower( ), iswprint( ), iswpunct( ), 22026 iswspace( ), iswupper( ), iswxdigit( ), setlocale( ), wctype( ), the Base Definitions volume of | 22027 IEEE Std. 1003.1-200x, , | 22028 CHANGE HISTORY 22029 First released as World-wide Portability Interfaces in Issue 4. 22030 Issue 5 22031 The following change has been made in this issue for alignment with 22032 ISO/IEC 9899: 1990/Amendment 1: 1995 (E): 22033 * The SYNOPSIS has been changed to indicate that this function and associated data types are 22034 now made visible by inclusion of the header rather than . 1174 Technical Standard (2000) (Draft July 31, 2000) System Interfaces iswdigit( ) 22035 NAME 22036 iswdigit - test for a decimal digit wide-character code 22037 SYNOPSIS 22038 #include 22039 int iswdigit(wint_t wc); 22040 DESCRIPTION 22041 CX The functionality described on this reference page is aligned with the ISO C standard. Any 22042 conflict between the requirements described here and the ISO C standard is unintentional. This 22043 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 22044 The iswdigit( ) function shall test whether wc is a wide-character code representing a character of 22045 class digit in the program's current locale; see the Base Definitions volume of | 22046 IEEE Std. 1003.1-200x, Chapter 7, Locale. | 22047 In all cases wc is a wint_t, the value of which the application shall ensure is a wide-character 22048 code corresponding to a valid character in the current locale, or equal to the value of the macro 22049 WEOF. If the argument has any other value, the behavior is undefined. 22050 RETURN VALUE 22051 The iswdigit( ) function shall return non-zero if wc is a decimal digit wide-character code; 22052 otherwise, it shall return 0. 22053 ERRORS 22054 No errors are defined. 22055 EXAMPLES 22056 None. 22057 APPLICATION USAGE 22058 To ensure applications portability, especially across natural languages, only this function and 22059 those listed in the SEE ALSO section should be used for classification of wide-character codes. 22060 RATIONALE 22061 None. 22062 FUTURE DIRECTIONS 22063 None. 22064 SEE ALSO 22065 iswalnum( ), iswalpha( ), iswcntrl( ), iswctype( ), iswgraph( ), iswlower( ), iswprint( ), iswpunct( ), 22066 iswspace( ), iswupper( ), iswxdigit( ), setlocale( ), the Base Definitions volume of | 22067 IEEE Std. 1003.1-200x, , | 22068 CHANGE HISTORY 22069 First released in Issue 4. 22070 Issue 5 22071 The following change has been made in this issue for alignment with 22072 ISO/IEC 9899: 1990/Amendment 1: 1995 (E): 22073 * The SYNOPSIS has been changed to indicate that this function and associated data types are 22074 now made visible by inclusion of the header rather than . 22075 Issue 6 22076 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1175 iswgraph( ) System Interfaces 22077 NAME 22078 iswgraph - test for a visible wide-character code 22079 SYNOPSIS 22080 #include 22081 int iswgraph(wint_t wc); 22082 DESCRIPTION 22083 CX The functionality described on this reference page is aligned with the ISO C standard. Any 22084 conflict between the requirements described here and the ISO C standard is unintentional. This 22085 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 22086 The iswgraph( ) function shall test whether wc is a wide-character code representing a character 22087 of class graph in the program's current locale; see the Base Definitions volume of | 22088 IEEE Std. 1003.1-200x, Chapter 7, Locale. | 22089 In all cases wc is a wint_t, the value of which the application shall ensure is a wide-character 22090 code corresponding to a valid character in the current locale, or equal to the value of the macro 22091 WEOF. If the argument has any other value, the behavior is undefined. 22092 RETURN VALUE 22093 The iswgraph( ) function shall return non-zero if wc is a wide-character code with a visible 22094 representation; otherwise, it shall return 0. 22095 ERRORS 22096 No errors are defined. 22097 EXAMPLES 22098 None. 22099 APPLICATION USAGE 22100 To ensure applications portability, especially across natural languages, only this function and 22101 those listed in the SEE ALSO section should be used for classification of wide-character codes. 22102 RATIONALE 22103 None. 22104 FUTURE DIRECTIONS 22105 None. 22106 SEE ALSO 22107 iswalnum( ), iswalpha( ), iswcntrl( ), iswctype( ), iswdigit( ), iswlower( ), iswprint( ), iswpunct( ), 22108 iswspace( ), iswupper( ), iswxdigit( ), setlocale( ), the Base Definitions volume of | 22109 IEEE Std. 1003.1-200x, , , the Base Definitions volume of | 22110 IEEE Std. 1003.1-200x, Chapter 7, Locale | 22111 CHANGE HISTORY 22112 First released in Issue 4. 22113 Issue 5 22114 The following change has been made in this issue for alignment with 22115 ISO/IEC 9899: 1990/Amendment 1: 1995 (E): 22116 * The SYNOPSIS has been changed to indicate that this function and associated data types are 22117 now made visible by inclusion of the header rather than . 1176 Technical Standard (2000) (Draft July 31, 2000) System Interfaces iswgraph( ) 22118 Issue 6 22119 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1177 iswlower( ) System Interfaces 22120 NAME 22121 iswlower - test for a lowercase letter wide-character code 22122 SYNOPSIS 22123 #include 22124 int iswlower(wint_t wc); 22125 DESCRIPTION 22126 CX The functionality described on this reference page is aligned with the ISO C standard. Any 22127 conflict between the requirements described here and the ISO C standard is unintentional. This 22128 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 22129 The iswlower( ) function shall test whether wc is a wide-character code representing a character 22130 of class lower in the program's current locale; see the Base Definitions volume of | 22131 IEEE Std. 1003.1-200x, Chapter 7, Locale. | 22132 In all cases wc is a wint_t, the value of which the application shall ensure is a wide-character 22133 code corresponding to a valid character in the current locale, or equal to the value of the macro 22134 WEOF. If the argument has any other value, the behavior is undefined. 22135 RETURN VALUE 22136 The iswlower( ) function shall return non-zero if wc is a lowercase letter wide-character code; 22137 otherwise, it shall return 0. 22138 ERRORS 22139 No errors are defined. 22140 EXAMPLES 22141 None. 22142 APPLICATION USAGE 22143 To ensure applications portability, especially across natural languages, only this function and 22144 those listed in the SEE ALSO section should be used for classification of wide-character codes. 22145 RATIONALE 22146 None. 22147 FUTURE DIRECTIONS 22148 None. 22149 SEE ALSO 22150 iswalnum( ), iswalpha( ), iswcntrl( ), iswctype( ), iswdigit( ), iswgraph( ), iswprint( ), iswpunct( ), 22151 iswspace( ), iswupper( ), iswxdigit( ), setlocale( ), the Base Definitions volume of | 22152 IEEE Std. 1003.1-200x, , , the Base Definitions volume of | 22153 IEEE Std. 1003.1-200x, Chapter 7, Locale | 22154 CHANGE HISTORY 22155 First released in Issue 4. 22156 Issue 5 22157 The following change has been made in this issue for alignment with 22158 ISO/IEC 9899: 1990/Amendment 1: 1995 (E): 22159 * The SYNOPSIS has been changed to indicate that this function and associated data types are 22160 now made visible by inclusion of the header rather than . 1178 Technical Standard (2000) (Draft July 31, 2000) System Interfaces iswlower( ) 22161 Issue 6 22162 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1179 iswprint( ) System Interfaces 22163 NAME 22164 iswprint - test for a printing wide-character code 22165 SYNOPSIS 22166 #include 22167 int iswprint(wint_t wc); 22168 DESCRIPTION 22169 CX The functionality described on this reference page is aligned with the ISO C standard. Any 22170 conflict between the requirements described here and the ISO C standard is unintentional. This 22171 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 22172 The iswprint( ) function shall test whether wc is a wide-character code representing a character of 22173 class print in the program's current locale; see the Base Definitions volume of | 22174 IEEE Std. 1003.1-200x, Chapter 7, Locale. | 22175 In all cases wc is a wint_t, the value of which the application shall ensure is a wide-character 22176 code corresponding to a valid character in the current locale, or equal to the value of the macro 22177 WEOF. If the argument has any other value, the behavior is undefined. 22178 RETURN VALUE 22179 The iswprint( ) function shall return non-zero if wc is a printing wide-character code; otherwise, it 22180 shall return 0. 22181 ERRORS 22182 No errors are defined. 22183 EXAMPLES 22184 None. 22185 APPLICATION USAGE 22186 To ensure applications portability, especially across natural languages, only this function and 22187 those listed in the SEE ALSO section should be used for classification of wide-character codes. 22188 RATIONALE 22189 None. 22190 FUTURE DIRECTIONS 22191 None. 22192 SEE ALSO 22193 iswalnum( ), iswalpha( ), iswcntrl( ), iswctype( ), iswdigit( ), iswgraph( ), iswlower( ), iswpunct( ), 22194 iswspace( ), iswupper( ), iswxdigit( ), setlocale( ), the Base Definitions volume of | 22195 IEEE Std. 1003.1-200x, , , the Base Definitions volume of | 22196 IEEE Std. 1003.1-200x, Chapter 7, Locale | 22197 CHANGE HISTORY 22198 First released in Issue 4. 22199 Issue 5 22200 The following change has been made in this issue for alignment with 22201 ISO/IEC 9899: 1990/Amendment 1: 1995 (E): 22202 * The SYNOPSIS has been changed to indicate that this function and associated data types are 22203 now made visible by inclusion of the header rather than . 1180 Technical Standard (2000) (Draft July 31, 2000) System Interfaces iswprint( ) 22204 Issue 6 22205 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1181 iswpunct( ) System Interfaces 22206 NAME 22207 iswpunct - test for a punctuation wide-character code 22208 SYNOPSIS 22209 #include 22210 int iswpunct(wint_t wc); 22211 DESCRIPTION 22212 CX The functionality described on this reference page is aligned with the ISO C standard. Any 22213 conflict between the requirements described here and the ISO C standard is unintentional. This 22214 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 22215 The iswpunct( ) function shall test whether wc is a wide-character code representing a character 22216 of class punct in the program's current locale; see the Base Definitions volume of | 22217 IEEE Std. 1003.1-200x, Chapter 7, Locale. | 22218 In all cases wc is a wint_t, the value of which the application shall ensure is a wide-character 22219 code corresponding to a valid character in the current locale, or equal to the value of the macro 22220 WEOF. If the argument has any other value, the behavior is undefined. 22221 RETURN VALUE 22222 The iswpunct( ) function shall return non-zero if wc is a punctuation wide-character code; 22223 otherwise, it shall return 0. 22224 ERRORS 22225 No errors are defined. 22226 EXAMPLES 22227 None. 22228 APPLICATION USAGE 22229 To ensure applications portability, especially across natural languages, only this function and 22230 those listed in the SEE ALSO section should be used for classification of wide-character codes. 22231 RATIONALE 22232 None. 22233 FUTURE DIRECTIONS 22234 None. 22235 SEE ALSO 22236 iswalnum( ), iswalpha( ), iswcntrl( ), iswctype( ), iswdigit( ), iswgraph( ), iswlower( ), iswprint( ), 22237 iswspace( ), iswupper( ), iswxdigit( ), setlocale( ), the Base Definitions volume of | 22238 IEEE Std. 1003.1-200x, , , the Base Definitions volume of | 22239 IEEE Std. 1003.1-200x, Chapter 7, Locale | 22240 CHANGE HISTORY 22241 First released in Issue 4. 22242 Issue 5 22243 The following change has been made in this issue for alignment with 22244 ISO/IEC 9899: 1990/Amendment 1: 1995 (E): 22245 * The SYNOPSIS has been changed to indicate that this function and associated data types are 22246 now made visible by inclusion of the header rather than . 1182 Technical Standard (2000) (Draft July 31, 2000) System Interfaces iswpunct( ) 22247 Issue 6 22248 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1183 iswspace( ) System Interfaces 22249 NAME 22250 iswspace - test for a white-space wide-character code 22251 SYNOPSIS 22252 #include 22253 int iswspace(wint_t wc); 22254 DESCRIPTION 22255 CX The functionality described on this reference page is aligned with the ISO C standard. Any 22256 conflict between the requirements described here and the ISO C standard is unintentional. This 22257 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 22258 The iswspace( ) function shall test whether wc is a wide-character code representing a character of 22259 class space in the program's current locale; see the Base Definitions volume of | 22260 IEEE Std. 1003.1-200x, Chapter 7, Locale. | 22261 In all cases wc is a wint_t, the value of which the application shall ensure is a wide-character 22262 code corresponding to a valid character in the current locale, or equal to the value of the macro 22263 WEOF. If the argument has any other value, the behavior is undefined. 22264 RETURN VALUE 22265 The iswspace( ) function shall return non-zero if wc is a white-space wide-character code; 22266 otherwise, it shall return 0. 22267 ERRORS 22268 No errors are defined. 22269 EXAMPLES 22270 None. 22271 APPLICATION USAGE 22272 To ensure applications portability, especially across natural languages, only this function and 22273 those listed in the SEE ALSO section should be used for classification of wide-character codes. 22274 RATIONALE 22275 None. 22276 FUTURE DIRECTIONS 22277 None. 22278 SEE ALSO 22279 iswalnum( ), iswalpha( ), iswcntrl( ), iswctype( ), iswdigit( ), iswgraph( ), iswlower( ), iswprint( ), 22280 iswpunct( ), iswupper( ), iswxdigit( ), setlocale( ), the Base Definitions volume of | 22281 IEEE Std. 1003.1-200x, , , the Base Definitions volume of | 22282 IEEE Std. 1003.1-200x, Chapter 7, Locale | 22283 CHANGE HISTORY 22284 First released in Issue 4. 22285 Issue 5 22286 The following change has been made in this issue for alignment with 22287 ISO/IEC 9899: 1990/Amendment 1: 1995 (E): 22288 * The SYNOPSIS has been changed to indicate that this function and associated data types are 22289 now made visible by inclusion of the header rather than . 1184 Technical Standard (2000) (Draft July 31, 2000) System Interfaces iswspace( ) 22290 Issue 6 22291 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1185 iswupper( ) System Interfaces 22292 NAME 22293 iswupper - test for an uppercase letter wide-character code 22294 SYNOPSIS 22295 #include 22296 int iswupper(wint_t wc); 22297 DESCRIPTION 22298 CX The functionality described on this reference page is aligned with the ISO C standard. Any 22299 conflict between the requirements described here and the ISO C standard is unintentional. This 22300 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 22301 The iswupper( ) function shall test whether wc is a wide-character code representing a character 22302 of class upper in the program's current locale; see the Base Definitions volume of | 22303 IEEE Std. 1003.1-200x, Chapter 7, Locale. | 22304 In all cases wc is a wint_t, the value of which the application shall ensure is a wide-character 22305 code corresponding to a valid character in the current locale, or equal to the value of the macro 22306 WEOF. If the argument has any other value, the behavior is undefined. 22307 RETURN VALUE 22308 The iswupper( ) function shall return non-zero if wc is an uppercase letter wide-character code; 22309 otherwise, it shall return 0. 22310 ERRORS 22311 No errors are defined. 22312 EXAMPLES 22313 None. 22314 APPLICATION USAGE 22315 To ensure applications portability, especially across natural languages, only this function and 22316 those listed in the SEE ALSO section should be used for classification of wide-character codes. 22317 RATIONALE 22318 None. 22319 FUTURE DIRECTIONS 22320 None. 22321 SEE ALSO 22322 iswalnum( ), iswalpha( ), iswcntrl( ), iswctype( ), iswdigit( ), iswgraph( ), iswlower( ), iswprint( ), 22323 iswpunct( ), iswspace( ), iswxdigit( ), setlocale( ), the Base Definitions volume of | 22324 IEEE Std. 1003.1-200x, , , the Base Definitions volume of | 22325 IEEE Std. 1003.1-200x, Chapter 7, Locale | 22326 CHANGE HISTORY 22327 First released in Issue 4. 22328 Issue 5 22329 The following change has been made in this issue for alignment with 22330 ISO/IEC 9899: 1990/Amendment 1: 1995 (E): 22331 * The SYNOPSIS has been changed to indicate that this function and associated data types are 22332 now made visible by inclusion of the header rather than . 1186 Technical Standard (2000) (Draft July 31, 2000) System Interfaces iswupper( ) 22333 Issue 6 22334 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1187 iswxdigit( ) System Interfaces 22335 NAME 22336 iswxdigit - test for a hexadecimal digit wide-character code 22337 SYNOPSIS 22338 #include 22339 int iswxdigit(wint_t wc); 22340 DESCRIPTION 22341 CX The functionality described on this reference page is aligned with the ISO C standard. Any 22342 conflict between the requirements described here and the ISO C standard is unintentional. This 22343 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 22344 The iswxdigit( ) function shall test whether wc is a wide-character code representing a character 22345 of class xdigit in the program's current locale; see the Base Definitions volume of | 22346 IEEE Std. 1003.1-200x, Chapter 7, Locale. | 22347 In all cases wc is a wint_t, the value of which the application shall ensure is a wide-character 22348 code corresponding to a valid character in the current locale, or equal to the value of the macro 22349 WEOF. If the argument has any other value, the behavior is undefined. 22350 RETURN VALUE 22351 The iswxdigit( ) function shall return non-zero if wc is a hexadecimal digit wide-character code; 22352 otherwise, it shall return 0. 22353 ERRORS 22354 No errors are defined. 22355 EXAMPLES 22356 None. 22357 APPLICATION USAGE 22358 To ensure applications portability, especially across natural languages, only this function and 22359 those listed in the SEE ALSO section should be used for classification of wide-character codes. 22360 RATIONALE 22361 None. 22362 FUTURE DIRECTIONS 22363 None. 22364 SEE ALSO 22365 iswalnum( ), iswalpha( ), iswcntrl( ), iswctype( ), iswdigit( ), iswgraph( ), iswlower( ), iswprint( ), 22366 iswpunct( ), iswspace( ), iswupper( ), setlocale( ), the Base Definitions volume of | 22367 IEEE Std. 1003.1-200x, , | 22368 CHANGE HISTORY 22369 First released in Issue 4. 22370 Issue 5 22371 The following change has been made in this issue for alignment with 22372 ISO/IEC 9899: 1990/Amendment 1: 1995 (E): 22373 * The SYNOPSIS has been changed to indicate that this function and associated data types are 22374 now made visible by inclusion of the header rather than . 22375 Issue 6 22376 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 1188 Technical Standard (2000) (Draft July 31, 2000) System Interfaces isxdigit( ) 22377 NAME 22378 isxdigit - test for a hexadecimal digit 22379 SYNOPSIS 22380 #include 22381 int isxdigit(int c); 22382 DESCRIPTION 22383 CX The functionality described on this reference page is aligned with the ISO C standard. Any 22384 conflict between the requirements described here and the ISO C standard is unintentional. This 22385 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 22386 The isxdigit( ) function shall test whether c is a character of class xdigit in the program's current | 22387 locale; see the Base Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale. | 22388 In all cases c is an int, the value of which the application shall ensure is a character representable 22389 as an unsigned char or equal to the value of the macro EOF. If the argument has any other value, 22390 the behavior is undefined. 22391 RETURN VALUE 22392 The isxdigit( ) function shall return non-zero if c is a hexadecimal digit; otherwise, it shall return 22393 0. 22394 ERRORS 22395 No errors are defined. 22396 EXAMPLES 22397 None. 22398 APPLICATION USAGE 22399 To ensure applications portability, especially across natural languages, only this function and 22400 those listed in the SEE ALSO section should be used for character classification. 22401 RATIONALE 22402 None. 22403 FUTURE DIRECTIONS 22404 None. 22405 SEE ALSO 22406 isalnum( ), isalpha( ), iscntrl( ), isdigit( ), isgraph( ), islower( ), isprint( ), ispunct( ), isspace( ), isupper( ), | 22407 the Base Definitions volume of IEEE Std. 1003.1-200x, | 22408 CHANGE HISTORY 22409 First released in Issue 1. Derived from Issue 1 of the SVID. | 22410 Issue 4 22411 The text of the DESCRIPTION is revised, although there are no functional differences between 22412 this issue and Issue 3. 22413 Issue 6 22414 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1189 j0( ) System Interfaces 22415 NAME 22416 j0, j1, jn - Bessel functions of the first kind 22417 SYNOPSIS 22418 XSI #include 22419 double j0(double x); 22420 double j1(double x); 22421 double jn(int n, double x); 22422 22423 DESCRIPTION 22424 The j0( ), j1( ), and jn( ) functions shall compute Bessel functions of x of the first kind of orders 0, 22425 1, and n respectively. 22426 An application wishing to check for error situations should set errno to 0 before calling j0( ), j1( ), 22427 or jn( ). If errno is non-zero on return, or the return value is NaN, an error has occurred. 22428 RETURN VALUE 22429 Upon successful completion, j0( ), j1( ), and jn( ) shall return the relevant Bessel value of x of the 22430 first kind. 22431 If the x argument is too large in magnitude, 0 shall be returned and errno may be set to 22432 [ERANGE]. | 22433 If x is NaN, NaN shall be returned and errno may be set to [EDOM]. | 22434 If the correct result would cause underflow, 0 shall be returned and errno may be set to 22435 [ERANGE]. 22436 ERRORS 22437 The j0( ), j1( ), and jn( ) functions may fail if: 22438 [EDOM] The value of x is NaN. | 22439 [ERANGE] The value of x was too large in magnitude, or underflow occurred. | 22440 No other errors shall occur. 22441 EXAMPLES 22442 None. 22443 APPLICATION USAGE 22444 None. 22445 RATIONALE 22446 None. 22447 FUTURE DIRECTIONS 22448 None. 22449 SEE ALSO 22450 isnan( ), y0( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 22451 CHANGE HISTORY 22452 First released in Issue 1. Derived from Issue 1 of the SVID. | 22453 Issue 4 22454 References to matherr( ) are removed. 22455 The RETURN VALUE and ERRORS sections are substantially rewritten to rationalize error 22456 handling in the mathematics functions. 1190 Technical Standard (2000) (Draft July 31, 2000) System Interfaces j0( ) 22457 Issue 5 22458 The DESCRIPTION is updated to indicate how an application should check for an error. This 22459 text was previously published in the APPLICATION USAGE section. System Interfaces, Issue 6 1191 jrand48( ) System Interfaces 22460 NAME 22461 jrand48 - generate a uniformly distributed pseudo-random long signed integer 22462 SYNOPSIS 22463 XSI #include 22464 long jrand48(unsigned short xsubi[3]); | 22465 | 22466 DESCRIPTION 22467 Refer to drand48( ). 1192 Technical Standard (2000) (Draft July 31, 2000) System Interfaces kill( ) 22468 NAME 22469 kill - send a signal to a process or a group of processes 22470 SYNOPSIS 22471 #include 22472 int kill(pid_t pid, int sig); 22473 DESCRIPTION 22474 The kill( ) function shall send a signal to a process or a group of processes specified by pid. The 22475 signal to be sent is specified by sig and is either one from the list given in or 0. If sig is 22476 0 (the null signal), error checking is performed but no signal is actually sent. The null signal can 22477 be used to check the validity of pid. 22478 For a process to have permission to send a signal to a process designated by pid, unless the 22479 sending process has appropriate privileges, the application shall ensure that the real or effective 22480 user ID of the sending process matchs the real or saved set-user-ID of the receiving process. 22481 If pid is greater than 0, sig shall be sent to the process whose process ID is equal to pid. 22482 If pid is 0, sig shall be sent to all processes (excluding an unspecified set of system processes) 22483 whose process group ID is equal to the process group ID of the sender, and for which the 22484 process has permission to send a signal. 22485 If pid is -1, sig shall be sent to all processes (excluding an unspecified set of system processes) for | 22486 which the process has permission to send that signal. | 22487 If pid is negative, but not -1, sig shall be sent to all processes (excluding an unspecified set of 22488 system processes) whose process group ID is equal to the absolute value of pid, and for which 22489 the process has permission to send a signal. 22490 If the value of pid causes sig to be generated for the sending process, and if sig is not blocked for 22491 the calling thread and if no other thread has sig unblocked or is waiting in a sigwait( ) function 22492 for sig, either sig or at least one pending unblocked signal shall be delivered to the sending 22493 thread before kill( ) returns. 22494 The user ID tests described above shall not be applied when sending SIGCONT to a process that 22495 is a member of the same session as the sending process. 22496 An implementation that provides extended security controls may impose further | 22497 implementation-defined restrictions on the sending of signals, including the null signal. In | 22498 particular, the system may deny the existence of some or all of the processes specified by pid. 22499 The kill( ) function is successful if the process has permission to send sig to any of the processes 22500 specified by pid. If kill( ) fails, no signal shall be sent. 22501 RETURN VALUE 22502 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno set to 22503 indicate the error. 22504 ERRORS 22505 The kill( ) function shall fail if: 22506 [EINVAL] The value of the sig argument is an invalid or unsupported signal number. | 22507 [EPERM] The process does not have permission to send the signal to any receiving | 22508 process. 22509 [ESRCH] No process or process group can be found corresponding to that specified by | 22510 pid. System Interfaces, Issue 6 1193 kill( ) System Interfaces 22511 EXAMPLES 22512 None. 22513 APPLICATION USAGE 22514 None. 22515 RATIONALE 22516 The semantics for permission checking for kill( ) differed between System V and most other 22517 implementations, such as Version 7 or 4.3 BSD. The semantics chosen for this volume of 22518 IEEE Std. 1003.1-200x agree with System V. Specifically, a set-user-ID process cannot protect 22519 itself against signals (or at least not against SIGKILL) unless it changes its real user ID. This 22520 choice allows the user who starts an application to send it signals even if it changes its effective 22521 user ID. The other semantics give more power to an application that wants to protect itself from 22522 the user who ran it. 22523 Some implementations provide semantic extensions to the kill( ) function when the absolute 22524 value of pid is greater than some maximum, or otherwise special, value. Negative values are a 22525 flag to kill( ). Since most implementations return [ESRCH] in this case, this behavior is not | 22526 included in this volume of IEEE Std. 1003.1-200x, although a conforming implementation could 22527 provide such an extension. 22528 The implementation-defined processes to which a signal cannot be sent may include the | 22529 scheduler or init. 22530 There was initially strong sentiment to specify that, if pid specifies that a signal be sent to the 22531 calling process and that signal is not blocked, that signal would be delivered before kill( ) 22532 returns. This would permit a process to call kill( ) and be guaranteed that the call never return. 22533 However, historical implementations that provide only the signal( ) function make only the 22534 weaker guarantee in this volume of IEEE Std. 1003.1-200x, because they only deliver one signal 22535 each time a process enters the kernel. Modifications to such implementations to support the 22536 sigaction( ) function generally require entry to the kernel following return from a signal-catching 22537 function, in order to restore the signal mask. Such modifications have the effect of satisfying the 22538 stronger requirement, at least when sigaction( ) is used, but not necessarily when signal( ) is used. 22539 The developers of this volume of IEEE Std. 1003.1-200x considered making the stronger 22540 requirement except when signal( ) is used, but felt this would be unnecessarily complex. 22541 Implementors are encouraged to meet the stronger requirement whenever possible. In practice, 22542 the weaker requirement is the same, except in the rare case when two signals arrive during a 22543 very short window. This reasoning also applies to a similar requirement for sigprocmask( ). 22544 In 4.2 BSD, the SIGCONT signal can be sent to any descendant process regardless of user-ID 22545 security checks. This allows a job control shell to continue a job even if processes in the job have 22546 altered their user IDs (as in the su command). In keeping with the addition of the concept of 22547 sessions, similar functionality is provided by allowing the SIGCONT signal to be sent to any 22548 process in the same session regardless of user ID security checks. This is less restrictive than BSD 22549 in the sense that ancestor processes (in the same session) can now be the recipient. It is more 22550 restrictive than BSD in the sense that descendant processes that form new sessions are now 22551 subject to the user ID checks. A similar relaxation of security is not necessary for the other job 22552 control signals since those signals are typically sent by the terminal driver in recognition of 22553 special characters being typed; the terminal driver bypasses all security checks. 22554 In secure implementations, a process may be restricted from sending a signal to a process having 22555 a different security label. In order to prevent the existence or nonexistence of a process from 22556 being used as a covert channel, such processes should appear nonexistent to the sender; that is, 22557 [ESRCH] should be returned, rather than [EPERM], if pid refers only to such processes. | 1194 Technical Standard (2000) (Draft July 31, 2000) System Interfaces kill( ) 22558 Existing implementations vary on the result of a kill( ) with pid indicating an inactive process (a 22559 terminated process that has not been waited for by its parent). Some indicate success on such a 22560 call (subject to permission checking), while others give an error of [ESRCH]. Since the definition 22561 of process lifetime in this volume of IEEE Std. 1003.1-200x covers inactive processes, the 22562 [ESRCH] error as described is inappropriate in this case. In particular, this means that an 22563 application cannot have a parent process check for termination of a particular child with kill( ). 22564 (Usually this is done with the null signal; this can be done reliably with waitpid( ).) 22565 There is some belief that the name kill( ) is misleading, since the function is not always intended 22566 to cause process termination. However, the name is common to all historical implementations, 22567 and any change would be in conflict with the goal of minimal changes to existing application 22568 code. 22569 FUTURE DIRECTIONS 22570 None. 22571 SEE ALSO 22572 getpid( ), raise( ), setsid( ), sigaction( ), sigqueue( ), the Base Definitions volume of | 22573 IEEE Std. 1003.1-200x, , | 22574 CHANGE HISTORY 22575 First released in Issue 1. Derived from Issue 1 of the SVID. | 22576 Issue 4 22577 The header is now marked as optional (OH); this header need not be included on 22578 XSI-conformant systems. 22579 The DESCRIPTION is clarified in various places. 22580 The following change is incorporated for alignment with the FIPS requirements: 22581 * In the DESCRIPTION, the second paragraph is reworded to indicate that the saved set-user- 22582 ID of the calling process is checked in place of its effective user ID. This functionality is 22583 marked as an extension. 22584 Issue 5 22585 The DESCRIPTION is updated for alignment with POSIX Threads Extension. 22586 Issue 6 22587 In the SYNOPSIS, the inclusion of is no longer required. 22588 The following new requirements on POSIX implementations derive from alignment with the 22589 Single UNIX Specification: 22590 * In the DESCRIPTION, the second paragraph is reworded to indicate that the saved set-user- 22591 ID of the calling process is checked in place of its effective user ID. This is a FIPS 22592 requirement. 22593 * The requirement to include has been removed. Although was 22594 required for conforming implementations of previous POSIX specifications, it was not 22595 required for UNIX applications. 22596 * The behavior when pid is -1 is now specified. It was previously explicitly unspecified in the 22597 POSIX.1-1988 standard. 22598 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1195 killpg( ) System Interfaces 22599 NAME 22600 killpg - send a signal to a process group 22601 SYNOPSIS 22602 XSI #include 22603 int killpg(pid_t pgrp, int sig); 22604 22605 DESCRIPTION 22606 The killpg( ) function shall send the signal specified by sig to the process group specified by pgrp. 22607 If pgrp is greater than 1, killpg(pgrp, sig) shall be equivalent to kill(-pgrp, sig). If pgrp is less than or 22608 equal to 1, the behavior of killpg( ) is undefined. 22609 RETURN VALUE 22610 Refer to kill( ). 22611 ERRORS 22612 Refer to kill( ). 22613 EXAMPLES 22614 None. 22615 APPLICATION USAGE 22616 None. 22617 RATIONALE 22618 None. 22619 FUTURE DIRECTIONS 22620 None. 22621 SEE ALSO 22622 getpgid( ), getpid( ), kill( ), raise( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 22623 22624 CHANGE HISTORY 22625 First released in Issue 4, Version 2. 22626 Issue 5 22627 Moved from X/OPEN UNIX extension to BASE. 1196 Technical Standard (2000) (Draft July 31, 2000) System Interfaces l64a( ) 22628 NAME 22629 l64a - convert a 32-bit integer to a radix-64 ASCII string 22630 SYNOPSIS 22631 XSI #include 22632 char *l64a(long value); 22633 22634 DESCRIPTION 22635 Refer to a64l( ). System Interfaces, Issue 6 1197 labs( ) System Interfaces 22636 NAME 22637 labs, llabs - return a long integer absolute value | 22638 SYNOPSIS 22639 #include 22640 long labs(long i); | 22641 long long llabs(long long i); | 22642 DESCRIPTION | 22643 CX The functionality described on this reference page is aligned with the ISO C standard. Any 22644 conflict between the requirements described here and the ISO C standard is unintentional. This 22645 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 22646 These functions shall compute the absolute value of the long integer operand, i. If the result | 22647 cannot be represented, the behavior is undefined. 22648 RETURN VALUE 22649 These functions shall return the absolute value of the long integer operand. | 22650 ERRORS 22651 No errors are defined. 22652 EXAMPLES 22653 None. 22654 APPLICATION USAGE 22655 None. 22656 RATIONALE 22657 None. 22658 FUTURE DIRECTIONS 22659 None. 22660 SEE ALSO 22661 abs( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 22662 CHANGE HISTORY 22663 First released in Issue 4. Derived from the ISO C standard. | 22664 Issue 6 | 22665 The llabs( ) function is added for alignment with the ISO/IEC 9899: 1999 standard. | 1198 Technical Standard (2000) (Draft July 31, 2000) System Interfaces lchown( ) 22666 NAME 22667 lchown - change the owner and group of a symbolic link 22668 SYNOPSIS 22669 XSI #include 22670 int lchown(const char *path, uid_t owner, gid_t group); 22671 22672 DESCRIPTION 22673 The lchown( ) function shall have the same effect as chown( ) except in the case where the named 22674 file is a symbolic link. In this case, lchown( ) shall change the ownership of the symbolic link file 22675 itself, while chown( ) changes the ownership of the file or directory to which the symbolic link 22676 refers. 22677 RETURN VALUE 22678 Upon successful completion, lchown( ) shall return 0. Otherwise, it shall return -1 and set errno to 22679 indicate an error. 22680 ERRORS 22681 The lchown( ) function shall fail if: 22682 [EACCES] Search permission is denied on a component of the path prefix of path. | 22683 [EINVAL] The owner or group ID is not a value supported by the implementation. | 22684 [ELOOP] A loop exists in symbolic links encountered during resolution of the path | 22685 argument. | 22686 [ENAMETOOLONG] | 22687 The length of a path name exceeds {PATH_MAX} or a path name component | 22688 is longer than {NAME_MAX}. | 22689 [ENOENT] A component of path does not name an existing file or path is an empty string. | 22690 [ENOTDIR] A component of the path prefix of path is not a directory. | 22691 [EOPNOTSUPP] The path argument names a symbolic link and the implementation does not | 22692 support setting the owner or group of a symbolic link. | 22693 [EPERM] The effective user ID does not match the owner of the file and the process | 22694 does not have appropriate privileges. 22695 [EROFS] The file resides on a read-only file system. | 22696 The lchown( ) function may fail if: 22697 [EIO] An I/O error occurred while reading or writing to the file system. | 22698 [EINTR] A signal was caught during execution of the function. | 22699 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during | 22700 resolution of the path argument. | 22701 [ENAMETOOLONG] | 22702 Path name resolution of a symbolic link produced an intermediate result 22703 whose length exceeds {PATH_MAX}. System Interfaces, Issue 6 1199 lchown( ) System Interfaces 22704 EXAMPLES 22705 Changing the Current Owner of a File 22706 The following example shows how to change the ownership of the symbolic link named 22707 /modules/pass1 to the user ID associated with ``jones'' and the group ID associated with ``cnd''. 22708 The numeric value for the user ID is obtained by using the getpwnam( ) function. The numeric 22709 value for the group ID is obtained by using the getgrnam( ) function. 22710 #include 22711 #include 22712 #include 22713 #include 22714 struct passwd *pwd; 22715 struct group *grp; 22716 char *path = "/modules/pass1"; 22717 ... 22718 pwd = getpwnam("jones"); 22719 grp = getgrnam("cnd"); 22720 lchown(path, pwd->pw_uid, grp->gr_gid); 22721 APPLICATION USAGE 22722 None. 22723 RATIONALE 22724 None. 22725 FUTURE DIRECTIONS 22726 None. 22727 SEE ALSO 22728 chown( ), symlink( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 22729 CHANGE HISTORY 22730 First released in Issue 4, Version 2. 22731 Issue 5 22732 Moved from X/OPEN UNIX extension to BASE. | 22733 Issue 6 | 22734 The wording of the mandatory [ELOOP] error condition is updated, and a second optional | 22735 [ELOOP] error condition is added. | 1200 Technical Standard (2000) (Draft July 31, 2000) System Interfaces lcong48( ) 22736 NAME 22737 lcong48 - seed a uniformly distributed pseudo-random signed long integer generator 22738 SYNOPSIS 22739 XSI #include 22740 void lcong48(unsigned short param[7]); | 22741 | 22742 DESCRIPTION 22743 Refer to drand48( ). System Interfaces, Issue 6 1201 ldexp( ) System Interfaces 22744 NAME 22745 ldexp, ldexpf, ldexpl - load exponent of a floating point number | 22746 SYNOPSIS 22747 #include 22748 double ldexp(double x, int exp); 22749 float ldexpf(float x, int exp); | 22750 long double ldexpl(long double x, int exp); | 22751 DESCRIPTION | 22752 CX The functionality described on this reference page is aligned with the ISO C standard. Any 22753 conflict between the requirements described here and the ISO C standard is unintentional. This 22754 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 22755 These functions shall compute the quantity x * 2exp. | 22756 An application wishing to check for error situations should set errno to 0 before calling ldexp( ). 22757 If errno is non-zero on return, or the return value is NaN, an error has occurred. 22758 RETURN VALUE 22759 Upon successful completion, these functions shall return x multiplied by 2, raised to the power | 22760 exp. 22761 XSI If the value of x is NaN, NaN shall be returned and errno may be set to [EDOM]. | 22762 If ldexp( ) would cause overflow, ±HUGE_VAL shall be returned (according to the sign of x), and 22763 errno shall be set to [ERANGE]. | 22764 If ldexp( ) would cause underflow, 0 shall be returned and errno may be set to [ERANGE]. 22765 ERRORS 22766 These functions shall fail if: | 22767 [ERANGE] The value to be returned would have caused overflow. | 22768 These functions may fail if: | 22769 XSI [EDOM] The argument x is NaN. | 22770 [ERANGE] The value to be returned would have caused underflow. | 22771 No other errors shall occur. 22772 EXAMPLES 22773 None. 22774 APPLICATION USAGE 22775 None. 22776 RATIONALE 22777 None. 22778 FUTURE DIRECTIONS 22779 None. 22780 SEE ALSO 22781 frexp( ), isnan( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 1202 Technical Standard (2000) (Draft July 31, 2000) System Interfaces ldexp( ) 22782 CHANGE HISTORY 22783 First released in Issue 1. Derived from Issue 1 of the SVID. | 22784 Issue 4 22785 References to matherr( ) are removed. 22786 The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 22787 ISO C standard and to rationalize error handling in the mathematics functions. 22788 The return value specified for [EDOM] is marked as an extension. 22789 Issue 5 22790 The DESCRIPTION is updated to indicate how an application should check for an error. This 22791 text was previously published in the APPLICATION USAGE section. | 22792 Issue 6 | 22793 The ldexpf( ) and ldexpl( ) functions are added for alignment with the ISO/IEC 9899: 1999 | 22794 standard. | System Interfaces, Issue 6 1203 ldiv( ) System Interfaces 22795 NAME 22796 ldiv, lldiv - compute quotient and remainder of a long division | 22797 SYNOPSIS 22798 #include 22799 ldiv_t ldiv(long numer, long denom); | 22800 lldiv_t lldiv(long long numer, long long denom); | 22801 DESCRIPTION | 22802 CX The functionality described on this reference page is aligned with the ISO C standard. Any 22803 conflict between the requirements described here and the ISO C standard is unintentional. This 22804 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 22805 These functions shall compute the quotient and remainder of the division of the numerator | 22806 numer by the denominator denom. If the division is inexact, the resulting quotient is the long | 22807 integer of lesser magnitude that is the nearest to the algebraic quotient. If the result cannot be | 22808 represented, the behavior is undefined; otherwise, quot * denom+rem shall equal numer. | 22809 RETURN VALUE 22810 These functions shall return a structure of type ldiv_t, comprising both the quotient and the | 22811 remainder. The structure includes the following members, in any order: 22812 long quot; /* Quotient */ 22813 long rem; /* Remainder */ 22814 ERRORS 22815 No errors are defined. 22816 EXAMPLES 22817 None. 22818 APPLICATION USAGE 22819 None. 22820 RATIONALE 22821 None. 22822 FUTURE DIRECTIONS 22823 None. 22824 SEE ALSO 22825 div( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 22826 CHANGE HISTORY 22827 First released in Issue 4. Derived from the ISO C standard. | 22828 Issue 6 | 22829 The lldiv( ) function is added for alignment with the ISO/IEC 9899: 1999 standard. | 1204 Technical Standard (2000) (Draft July 31, 2000) System Interfaces lfind( ) 22830 NAME 22831 lfind - find entry in a linear search table 22832 SYNOPSIS 22833 XSI #include 22834 void *lfind(const void *key, const void *base, size_t *nelp, 22835 size_t width, int (*compar)(const void *, const void *)); 22836 22837 DESCRIPTION 22838 Refer to lsearch( ). System Interfaces, Issue 6 1205 lgamma( ) System Interfaces 22839 NAME 22840 lgamma, lgammaf, lgammal - log gamma function | 22841 SYNOPSIS 22842 XSI #include 22843 double lgamma(double x); 22844 float lgammaf(float x); | 22845 long double lgammal(long double x); | 22846 extern int signgam; | 22847 22848 DESCRIPTION 22849 These functions function shall compute loge ( x) where ( x) is defined as e-ttx-1dt. The sign of | 22850 0 22851 ( x) is returned in the external integer signgam. The argument x need not be a non-positive | 22852 integer ( ( x) is defined over the reals, except the non-positive integers). 22853 An application wishing to check for error situations should set errno to 0 before calling lgamma( ). 22854 If errno is non-zero on return, or the return value is NaN, an error has occurred. 22855 These functions need not be reentrant. A function that is not required to be reentrant is not | 22856 required to be thread-safe. 22857 RETURN VALUE 22858 Upon successful completion, these functions shall return the logarithmic gamma of x. | 22859 If x is NaN, NaN shall be returned and errno may be set to [EDOM]. | 22860 If x is a non-positive integer, either HUGE_VAL or NaN shall be returned and errno may be set to | 22861 [ERANGE]. | 22862 If the correct value would cause overflow, lgamma( ) shall return HUGE_VAL and may set errno 22863 to [ERANGE]. | 22864 If the correct value would cause underflow, lgamma( ) shall return 0 and may set errno to 22865 [ERANGE]. 22866 ERRORS 22867 These functions may fail if: | 22868 [EDOM] The value of x is NaN. | 22869 [ERANGE] The value of x is a non-positive integer, or the value to be returned would | 22870 have caused overflow or underflow. | 22871 No other errors shall occur. 22872 EXAMPLES 22873 None. 22874 APPLICATION USAGE 22875 None. 22876 RATIONALE 22877 None. 22878 FUTURE DIRECTIONS 22879 None. 1206 Technical Standard (2000) (Draft July 31, 2000) System Interfaces lgamma( ) 22880 SEE ALSO 22881 exp( ), isnan( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 22882 CHANGE HISTORY 22883 First released in Issue 3. 22884 Issue 4 22885 This page no longer points to gamma( ), but contains all information relating to lgamma( ). 22886 The RETURN VALUE and ERRORS sections are substantially rewritten to rationalize error 22887 handling in the mathematics functions. 22888 Issue 5 22889 The DESCRIPTION is updated to indicate how an application should check for an error. This 22890 text was previously published in the APPLICATION USAGE section. 22891 A note indicating that this function need not be reentrant is added to the DESCRIPTION. | 22892 Issue 6 | 22893 The following changes are made for alignment with the ISO/IEC 9899: 1999 standard: | 22894 * The lgammaf( ) and lgammal( ) functions are added. | 22895 * The RETURN VALUE and ERRORS sections are updated so that when x is a non-positive | | 22896 integer, errno may be set to [ERANGE]; previously, this was [EDOM]. | System Interfaces, Issue 6 1207 link( ) System Interfaces 22897 NAME 22898 link - link to a file 22899 SYNOPSIS 22900 #include 22901 int link(const char *path1, const char *path2); 22902 DESCRIPTION 22903 The link( ) function shall create a new link (directory entry) for the existing file, path1. 22904 The path1 argument points to a path name naming an existing file. The path2 argument points to 22905 a path name naming the new directory entry to be created. The link( ) function shall atomically 22906 create a new link for the existing file and the link count of the file shall be incremented by one. 22907 If path1 names a directory, link( ) shall fail unless the process has appropriate privileges and the 22908 implementation supports using link( ) on directories. 22909 Upon successful completion, link( ) shall mark for update the st_ctime field of the file. Also, the 22910 st_ctime and st_mtime fields of the directory that contains the new entry shall be marked for 22911 update. 22912 If link( ) fails, no link shall be created and the link count of the file shall remain unchanged. 22913 The implementation may require that the calling process has permission to access the existing 22914 file. 22915 RETURN VALUE 22916 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno set to 22917 indicate the error. 22918 ERRORS 22919 The link( ) function shall fail if: 22920 [EACCES] A component of either path prefix denies search permission, or the requested | 22921 link requires writing in a directory that denies write permission, or the calling 22922 process does not have permission to access the existing file and this is 22923 required by the implementation. 22924 [EEXIST] The path2 argument resolves to an existing file or refers to a symbolic link. | 22925 [ELOOP] A loop exists in symbolic links encountered during resolution of the path1 or | 22926 path2 argument. | 22927 [EMLINK] The number of links to the file named by path1 would exceed {LINK_MAX}. | 22928 [ENAMETOOLONG] | 22929 The length of the path1 or path2 argument exceeds {PATH_MAX} or a path | 22930 name component is longer than {NAME_MAX}. | 22931 [ENOENT] A component of either path prefix does not exist; the file named by path1 does | 22932 not exist; or path1 or path2 points to an empty string. 22933 [ENOSPC] The directory to contain the link cannot be extended. | 22934 [ENOTDIR] A component of either path prefix is not a directory. | 22935 [EPERM] The file named by path1 is a directory and either the calling process does not | 22936 have appropriate privileges or the implementation prohibits using link( ) on 22937 directories. 1208 Technical Standard (2000) (Draft July 31, 2000) System Interfaces link( ) 22938 [EROFS] The requested link requires writing in a directory on a read-only file system. | 22939 [EXDEV] The link named by path2 and the file named by path1 are on different file | 22940 XSR systems and the implementation does not support links between file systems, 22941 or path1 refers to a named STREAM. 22942 The link( ) function may fail if: 22943 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 22944 resolution of the path1 or path2 argument. | 22945 [ENAMETOOLONG] | 22946 As a result of encountering a symbolic link in resolution of the path1 or path2 22947 argument, the length of the substituted path name string exceeded 22948 {PATH_MAX}. | 22949 EXAMPLES 22950 Creating a Link to a File 22951 The following example shows how to create a link to a file named /home/cnd/mod1 by creating a 22952 new directory entry named /modules/pass1. 22953 #include 22954 char *path1 = "/home/cnd/mod1"; 22955 char *path2 = "/modules/pass1"; 22956 int status; 22957 ... 22958 status = link (path1, path2); 22959 Creating a Link to a File Within a Program 22960 In the following program example, the link( ) function is used to link the /etc/passwd file 22961 (defined as PASSWDFILE) to a file named /etc/opasswd (defined as SAVEFILE), which is used 22962 to save the current password file. Then, after removing the current password file (defined as 22963 PASSWDFILE), the new password file is saved as the current password file using the link( ) 22964 function again. 22965 #include 22966 #define LOCKFILE "/etc/ptmp" 22967 #define PASSWDFILE "/etc/passwd" 22968 #define SAVEFILE "/etc/opasswd" 22969 ... 22970 /* Save current password file */ 22971 link (PASSWDFILE, SAVEFILE); 22972 /* Remove current password file. */ 22973 unlink (PASSWDFILE); 22974 /* Save new password file as current password file. */ 22975 link (LOCKFILE,PASSWDFILE); 22976 APPLICATION USAGE 22977 Some implementations do allow links between file systems. System Interfaces, Issue 6 1209 link( ) System Interfaces 22978 RATIONALE 22979 Linking to a directory is restricted to the superuser in most historical implementations because 22980 this capability may produce loops in the file hierarchy or otherwise corrupt the file system. This 22981 volume of IEEE Std. 1003.1-200x continues that philosophy by prohibiting link( ) and unlink( ) 22982 from doing this. Other functions could do it if the implementor designed such an extension. 22983 Some historical implementations allow linking of files on different file systems. Wording was 22984 added to explicitly allow this optional behavior. 22985 The exception for cross-file system links is intended to apply only to links that are 22986 programmatically indistinguishable from ``hard'' links. 22987 FUTURE DIRECTIONS 22988 None. 22989 SEE ALSO 22990 symlink( ), unlink( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 22991 CHANGE HISTORY 22992 First released in Issue 1. Derived from Issue 1 of the SVID. | 22993 Issue 4 22994 The header is added to the SYNOPSIS section. 22995 The following change is incorporated for alignment with the ISO POSIX-1 standard: 22996 * The type of arguments path1 and path2 are changed from char* to const char*. 22997 The following change is incorporated for alignment with the FIPS requirements: 22998 * In the ERRORS section, the condition whereby [ENAMETOOLONG] is returned if a path 22999 name component is larger that {NAME_MAX} is now defined as mandatory and marked as 23000 an extension. 23001 Issue 4, Version 2 23002 The ERRORS section is updated for X/OPEN UNIX conformance as follows: 23003 * The [ELOOP] error is returned if too many symbolic links are encountered during path name 23004 resolution. 23005 * The [EXDEV] error may also be returned if path1 refers to a named STREAM. 23006 * A second [ENAMETOOLONG] condition is defined that may report excessive length of an 23007 intermediate result of path name resolution of a symbolic link. 23008 Issue 6 23009 The following changes are made for alignment with the ISO POSIX-1: 1996 standard: 23010 * The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. 23011 This is since behavior may vary from one file system to another. 23012 The following new requirements on POSIX implementations derive from alignment with the 23013 Single UNIX Specification: 23014 * The [ELOOP] mandatory error condition is added. 23015 * A second [ENAMETOOLONG] is added as an optional error condition. 23016 The following changes were made to align with the IEEE P1003.1a draft standard: 23017 * An explanation is added of action when path2 refers to a symbolic link. 1210 Technical Standard (2000) (Draft July 31, 2000) System Interfaces link( ) 23018 * The [ELOOP] optional error condition is added. System Interfaces, Issue 6 1211 lio_listio( ) System Interfaces 23019 NAME 23020 lio_listio - list directed I/O (REALTIME) 23021 SYNOPSIS 23022 AIO #include 23023 int lio_listio(int mode, struct aiocb *restrict const list[restrict], | 23024 int nent, struct sigevent *restrict sig); | 23025 | 23026 DESCRIPTION 23027 The lio_listio ( ) function allows the calling process to initiate a list of I/O requests with a single 23028 function call. 23029 The mode argument takes one of the values LIO_WAIT or LIO_NOWAIT declared in and 23030 determines whether the function returns when the I/O operations have been completed, or as 23031 soon as the operations have been queued. If the mode argument is LIO_WAIT, the function waits 23032 until all I/O is complete and the sig argument is ignored. 23033 If the mode argument is LIO_NOWAIT, the function shall return immediately, and asynchronous 23034 notification shall occur, according to the sig argument, when all the I/O operations complete. If 23035 sig is NULL, then no asynchronous notification shall occur. If sig is not NULL, asynchronous 23036 notification occurs as specified in Section 2.4.1 (on page 528) when all the requests in list have 23037 completed. 23038 The I/O requests enumerated by list are submitted in an unspecified order. 23039 The list argument is an array of pointers to aiocb structures. The array contains nent elements. 23040 The array may contain NULL elements, which shall be ignored. 23041 The aio_lio_opcode field of each aiocb structure specifies the operation to be performed. The 23042 supported operations are LIO_READ, LIO_WRITE, and LIO_NOP; these symbols are defined in 23043 . The LIO_NOP operation causes the list entry to be ignored. If the aio_lio_opcode 23044 element is equal to LIO_READ, then an I/O operation is submitted as if by a call to aio_read( ) 23045 with the aiocbp equal to the address of the aiocb structure. If the aio_lio_opcode element is equal 23046 to LIO_WRITE, then an I/O operation is submitted as if by a call to aio_write( ) with the aiocbp 23047 equal to the address of the aiocb structure. 23048 The aio_fildes member specifies the file descriptor on which the operation is to be performed. 23049 The aio_buf member specifies the address of the buffer to or from which the data is transferred. 23050 The aio_nbytes member specifies the number of bytes of data to be transferred. 23051 The members of the aiocb structure further describe the I/O operation to be performed, in a 23052 manner identical to that of the corresponding aiocb structure when used by the aio_read( ) and 23053 aio_write( ) functions. 23054 The nent argument specifies how many elements are members of the list; that is, the length of the 23055 array. 23056 The behavior of this function is altered according to the definitions of synchronized I/O data 23057 integrity completion and synchronized I/O file integrity completion if synchronized I/O is 23058 enabled on the file associated with aio_fildes . 23059 For regular files, no data transfer shall occur past the offset maximum established in the open | 23060 file description associated with aiocbp->aio_fildes. | 1212 Technical Standard (2000) (Draft July 31, 2000) System Interfaces lio_listio( ) 23061 RETURN VALUE 23062 If the mode argument has the value LIO_NOWAIT, the lio_listio ( ) function shall return the value 23063 zero if the I/O operations are successfully queued; otherwise, the function shall return the value 23064 -1 and set errno to indicate the error. 23065 If the mode argument has the value LIO_WAIT, the lio_listio ( ) function shall return the value 23066 zero when all the indicated I/O has completed successfully. Otherwise, lio_listio ( ) shall return a 23067 value of -1 and set errno to indicate the error. 23068 In either case, the return value only indicates the success or failure of the lio_listio ( ) call itself, 23069 not the status of the individual I/O requests. In some cases one or more of the I/O requests 23070 contained in the list may fail. Failure of an individual request does not prevent completion of 23071 any other individual request. To determine the outcome of each I/O request, the application 23072 shall examine the error status associated with each aiocb control block. The error statuses so 23073 returned are identical to those returned as the result of an aio_read( ) or aio_write( ) function. 23074 ERRORS 23075 The lio_listio ( ) function shall fail if: 23076 [EAGAIN] The resources necessary to queue all the I/O requests were not available. The | 23077 application may check the error status for each aiocb to determine the 23078 individual request(s) that failed. 23079 [EAGAIN] The number of entries indicated by nent would cause the system-wide limit 23080 {AIO_MAX} to be exceeded. 23081 [EINVAL] The mode argument is not a proper value, or the value of nent was greater than | 23082 {AIO_LISTIO_MAX}. 23083 [EINTR] A signal was delivered while waiting for all I/O requests to complete during | 23084 an LIO_WAIT operation. Note that, since each I/O operation invoked by 23085 lio_listio ( ) may possibly provoke a signal when it completes, this error return 23086 may be caused by the completion of one (or more) of the very I/O operations 23087 being awaited. Outstanding I/O requests are not canceled, and the application 23088 shall examine each list element to determine whether the request was 23089 initiated, canceled, or completed. 23090 [EIO] One or more of the individual I/O operations failed. The application may | 23091 check the error status for each aiocb structure to determine the individual 23092 request(s) that failed. 23093 In addition to the errors returned by the lio_listio ( ) function, if the lio_listio ( ) function succeeds 23094 or fails with errors of [EAGAIN], [EINTR], or [EIO], then some of the I/O specified by the list 23095 may have been initiated. If the lio_listio ( ) function fails with an error code other than [EAGAIN], 23096 [EINTR], or [EIO], no operations from the list shall have been initiated. The I/O operation 23097 indicated by each list element can encounter errors specific to the individual read or write 23098 function being performed. In this event, the error status for each aiocb control block contains the 23099 associated error code. The error codes that can be set are the same as would be set by a read( ) or 23100 write( ) function, with the following additional error codes possible: 23101 [EAGAIN] The requested I/O operation was not queued due to resource limitations. | 23102 [ECANCELED] The requested I/O was canceled before the I/O completed due to an explicit | 23103 aio_cancel( ) request. | 23104 [EFBIG] The aiocbp->aio_lio_opcode is LIO_WRITE, the file is a regular file, aiocbp- | 23105 >aio_nbytes is greater than 0, and the aiocbp->aio_offset is greater than or equal | 23106 to the offset maximum in the open file description associated with aiocbp- | System Interfaces, Issue 6 1213 lio_listio( ) System Interfaces 23107 >aio_fildes. | 23108 [EINPROGRESS] The requested I/O is in progress. | 23109 [EOVERFLOW] The aiocbp->aio_lio_opcode is LIO_READ, the file is a regular file, aiocbp- | 23110 >aio_nbytes is greater than 0, and the aiocbp->aio_offset is before the end-of-file | 23111 and is greater than or equal to the offset maximum in the open file description | 23112 associated with aiocbp->aio_fildes. | 23113 EXAMPLES 23114 None. 23115 APPLICATION USAGE 23116 None. 23117 RATIONALE 23118 Although it may appear that there are inconsistencies in the specified circumstances for error 23119 codes, the [EIO] error condition applies when any circumstance relating to an individual | 23120 operation makes that operation fail. This might be due to a badly formulated request (for 23121 example, the aio_lio_opcode field is invalid, and aio_error( ) returns [EINVAL]) or might arise from | 23122 application behavior (for example, the file descriptor is closed before the operation is initiated, 23123 and aio_error( ) returns [EBADF]). | 23124 The limitation on the set of error codes returned when operations from the list shall have been 23125 initiated enables applications to know when operations have been started and whether 23126 aio_error( ) is valid for a specific operation. 23127 FUTURE DIRECTIONS 23128 None. 23129 SEE ALSO 23130 aio_read( ), aio_write( ), aio_error( ), aio_return( ), aio_cancel( ), close( ), exec, exit( ), fork( ), lseek( ), | 23131 read( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 23132 CHANGE HISTORY 23133 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 23134 Large File Summit extensions are added. 23135 Issue 6 23136 The [ENOSYS] error condition has been removed as stubs need not be provided if an 23137 implementation does not support the Asynchronous Input and Output option. | 23138 The lio_listio ( ) function is marked as part of the Asynchronous Input and Output option. | 23139 The following new requirements on POSIX implementations derive from alignment with the 23140 Single UNIX Specification: 23141 * In the DESCRIPTION, text is added to indicate that for regular files no data transfer occurs 23142 past the offset maximum established in the open file description associated with aiocbp- | 23143 >aio_fildes. This change is to support large files. | 23144 * The [EBIG] and [EOVERFLOW] error conditions are defined. This change is to support large 23145 files. 23146 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. | 23147 The restrict keyword is added to the lio_listio ( ) prototype for alignment with the | 23148 ISO/IEC 9899: 1999 standard. | 1214 Technical Standard (2000) (Draft July 31, 2000) System Interfaces listen( ) 23149 NAME 23150 listen - listen for socket connections and limit the queue of incoming connections 23151 SYNOPSIS 23152 #include 23153 int listen(int socket, int backlog); 23154 DESCRIPTION 23155 The listen( ) function shall mark a connection-mode socket, specified by the socket argument, as 23156 accepting connections. 23157 The backlog argument provides a hint to the implementation which the implementation shall use 23158 to limit the number of outstanding connections in the socket's listen queue. Implementations 23159 may impose a limit on backlog and silently reduce the specified value. Normally, a larger backlog 23160 argument value shall result in a larger or equal length of the listen queue. Implementations shall 23161 support values of backlog up to SOMAXCONN, defined in . 23162 The implementation may include incomplete connections in its listen queue. The limits on the 23163 number of incomplete connections and completed connections queued may be different. 23164 The implementation may have an upper limit on the length of the listen queue-either global or 23165 per accepting socket. If backlog exceeds this limit, the length of the listen queue is set to the limit. 23166 If listen( ) is called with a backlog argument value that is less than 0, the function behaves as if it 23167 had been called with a backlog argument value of 0. 23168 A backlog argument of 0 may allow the socket to accept connections, in which case the length of 23169 the listen queue may be set to an implementation-defined minimum value. | 23170 The socket in use may require the process to have appropriate privileges to use the listen( ) 23171 function. 23172 RETURN VALUE 23173 Upon successful completions, listen( ) shall return 0; otherwise, -1 shall be returned and errno set 23174 to indicate the error. 23175 ERRORS 23176 The listen( ) function shall fail if: 23177 [EBADF] The socket argument is not a valid file descriptor. 23178 [EDESTADDRREQ] 23179 The socket is not bound to a local address, and the protocol does not support 23180 listening on an unbound socket. 23181 [EINVAL] The socket is already connected. 23182 [ENOTSOCK] The socket argument does not refer to a socket. 23183 [EOPNOTSUPP] The socket protocol does not support listen( ). 23184 The listen( ) function may fail if: 23185 [EACCES] The calling process does not have the appropriate privileges. 23186 [EINVAL] The socket has been shut down. 23187 [ENOBUFS] Insufficient resources are available in the system to complete the call. System Interfaces, Issue 6 1215 listen( ) System Interfaces 23188 EXAMPLES 23189 None. 23190 APPLICATION USAGE 23191 None. 23192 RATIONALE 23193 None. 23194 FUTURE DIRECTIONS 23195 None. 23196 SEE ALSO 23197 accept( ), connect( ), socket( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 23198 CHANGE HISTORY 23199 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. | 23200 The DESCRIPTION is updated to describe the relationship of SOMAXCONN and the backlog | 23201 argument. 1216 Technical Standard (2000) (Draft July 31, 2000) System Interfaces llrint( ) 23202 NAME | 23203 llrint, llrintf, llrintl, lrint, lrintf, lrinfl - round to nearest integer value using current rounding | 23204 direction | 23205 SYNOPSIS | 23206 #include | 23207 long long llrint(double x); | 23208 long long llrintf(float x); | 23209 long long llrintl(long double x); | 23210 long lrint(double x); | 23211 long lrintf(float x); | 23212 long lrintl(long double x); | 23213 DESCRIPTION | 23214 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 23215 conflict between the requirements described here and the ISO C standard is unintentional. This | 23216 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 23217 These functions shall round their argument to the nearest integer value, rounding according to | 23218 the current rounding direction. | 23219 An application wishing to check for error situations should set errno to 0 before calling these | 23220 functions. If errno is non-zero on return, an error has occurred. | 23221 RETURN VALUE | 23222 Upon successful completion, these functions shall return the rounded integer value. | 23223 If the rounded value is outside the range of the return type, the numeric result is unspecified. | 23224 If the magnitude of x is too large, the numeric result is unspecified and errno may be set to | 23225 [ERANGE]. | 23226 ERRORS | 23227 These functions may fail if: | 23228 [ERANGE] The magnitude of x is too large. | 23229 EXAMPLES | 23230 None. | 23231 APPLICATION USAGE | 23232 None. | 23233 RATIONALE | 23234 None. | 23235 FUTURE DIRECTIONS | 23236 None. | 23237 SEE ALSO | 23238 The Base Definitions volume of IEEE Std. 1003.1-200x, | 23239 CHANGE HISTORY || 23240 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 1217 llround( ) System Interfaces 23241 NAME | 23242 llround, llroundf, llroundl, lround, lroundf, lroundl - round to nearest integer value | 23243 SYNOPSIS | 23244 #include | 23245 long long llround(double x); | 23246 long long llroundf(float x); | 23247 long long llroundl(long double x); | 23248 long lround(double x); | 23249 long lroundf(float x); | 23250 long lroundl(long double x); | 23251 DESCRIPTION | 23252 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 23253 conflict between the requirements described here and the ISO C standard is unintentional. This | 23254 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 23255 These functions shall round their argument to the nearest integer value, rounding halfway cases | 23256 away from zero, regardless of the current rounding direction. | 23257 An application wishing to check for error situations should set errno to 0 before calling these | 23258 functions. If errno is non-zero on return, an error has occurred. | 23259 RETURN VALUE | 23260 Upon successful completion, these functions shall return the rounded integer value. | 23261 If the rounded value is outside the range of the return type, the numeric result is unspecified. | 23262 If the magnitude of x is too large, the numeric result is unspecified and errno may be set to | 23263 [ERANGE]. | 23264 ERRORS | 23265 These functions may fail if: | 23266 [ERANGE] The magnitude of x is too large. | 23267 EXAMPLES | 23268 None. | 23269 APPLICATION USAGE | 23270 None. | 23271 RATIONALE | 23272 None. | 23273 FUTURE DIRECTIONS | 23274 None. | 23275 SEE ALSO | 23276 The Base Definitions volume of IEEE Std. 1003.1-200x, | 23277 CHANGE HISTORY || 23278 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | 1218 Technical Standard (2000) (Draft July 31, 2000) System Interfaces localeconv( ) 23279 NAME 23280 localeconv - return locale-specific information | 23281 SYNOPSIS 23282 #include 23283 struct lconv *localeconv(void); 23284 DESCRIPTION 23285 CX The functionality described on this reference page is aligned with the ISO C standard. Any 23286 conflict between the requirements described here and the ISO C standard is unintentional. This 23287 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 23288 The localeconv( ) function shall set the components of an object with the type struct lconv with 23289 the values appropriate for the formatting of numeric quantities (monetary and otherwise) 23290 according to the rules of the current locale. 23291 The members of the structure with type char* are pointers to strings, any of which (except 23292 decimal_point) can point to " ", to indicate that the value is not available in the current locale or 23293 is of zero length. The members with type char are non-negative numbers, any of which can be 23294 {CHAR_MAX} to indicate that the value is not available in the current locale. 23295 The members include the following: 23296 char *decimal_point 23297 The radix character used to format non-monetary quantities. 23298 char *thousands_sep 23299 The character used to separate groups of digits before the decimal-point character in 23300 formatted non-monetary quantities. 23301 char *grouping 23302 A string whose elements taken as one-byte integer values indicate the size of each group of 23303 digits in formatted non-monetary quantities. 23304 char *int_curr_symbol 23305 The international currency symbol applicable to the current locale. The first three 23306 characters contain the alphabetic international currency symbol in accordance with those 23307 specified in the ISO 4217: 1995 standard. The fourth character (immediately preceding the 23308 null byte) is the character used to separate the international currency symbol from the 23309 monetary quantity. 23310 char *currency_symbol 23311 The local currency symbol applicable to the current locale. 23312 char *mon_decimal_point 23313 The radix character used to format monetary quantities. 23314 char *mon_thousands_sep 23315 The separator for groups of digits before the decimal-point in formatted monetary 23316 quantities. 23317 char *mon_grouping 23318 A string whose elements taken as one-byte integer values indicate the size of each group of 23319 digits in formatted monetary quantities. 23320 char *positive_sign 23321 The string used to indicate a non-negative valued formatted monetary quantity. System Interfaces, Issue 6 1219 localeconv( ) System Interfaces 23322 char *negative_sign 23323 The string used to indicate a negative valued formatted monetary quantity. 23324 char int_frac_digits 23325 The number of fractional digits (those after the decimal-point) to be displayed in an 23326 internationally formatted monetary quantity. 23327 char frac_digits 23328 The number of fractional digits (those after the decimal-point) to be displayed in a 23329 formatted monetary quantity. 23330 char p_cs_precedes 23331 Set to 1 if the currency_symbol or int_curr_symbol precedes the value for a non-negative | 23332 formatted monetary quantity. Set to 0 if the symbol succeeds the value. 23333 char p_sep_by_space 23334 Set to 0 if no space separates the currency_symbol or int_curr_symbol from the value for a | 23335 non-negative formatted monetary quantity. Set to 1 if a space separates the symbol from the 23336 XSI value; and set to 2 if a space separates the symbol and the sign string, if adjacent. 23337 char n_cs_precedes 23338 Set to 1 if the currency_symbol or int_curr_symbol precedes the value for a negative | 23339 formatted monetary quantity. Set to 0 if the symbol succeeds the value. 23340 char n_sep_by_space 23341 Set to 0 if no space separates the currency_symbol or int_curr_symbol from the value for a | 23342 negative formatted monetary quantity. Set to 1 if a space separates the symbol from the 23343 XSI value; and set to 2 if a space separates the symbol and the sign string, if adjacent. 23344 char p_sign_posn 23345 Set to a value indicating the positioning of the positive_sign for a non-negative formatted 23346 monetary quantity. 23347 char n_sign_posn 23348 Set to a value indicating the positioning of the negative_sign for a negative formatted 23349 monetary quantity. | 23350 char int_p_cs_precedes | 23351 Set to 1 or 0 if the int_currency_symbol respectively precedes or succeeds the value for a | 23352 non-negative internationally formatted monetary quantity. | 23353 char int_n_cs_precedes | 23354 Set to 1 or 0 if the int_currency_symbol respectively precedes or succeeds the value for a | 23355 negative internationally formatted monetary quantity. | 23356 char int_p_sep_by_space | 23357 Set to a value indicating the separation of the int_currency_symbol, the sign string, and the | 23358 value for a non-negative internationally formatted monetary quantity. | 23359 char int_n_sep_by_space | 23360 Set to a value indicating the separation of the int_currency_symbol, the sign string, and the | 23361 value for a negative internationally formatted monetary quantity. | 23362 char int_p_sign_posn | 23363 Set to a value indicating the positioning of the positive_sign for a non-negative | 23364 internationally formatted monetary quantity. | 23365 char int_n_sign_posn | 23366 Set to a value indicating the positioning of the negative_sign for a negative internationally | 1220 Technical Standard (2000) (Draft July 31, 2000) System Interfaces localeconv( ) 23367 formatted monetary quantity. | 23368 The elements of grouping and mon_grouping are interpreted according to the following: 23369 {CHAR_MAX} No further grouping is to be performed. 23370 0 The previous element is to be repeatedly used for the remainder of the digits. 23371 other The integer value is the number of digits that comprise the current group. The 23372 next element is examined to determine the size of the next group of digits 23373 before the current group. 23374 The values of p_sep_by_space, n_sep_by_space, int_p_sep_by_space, and int_n_sep_by_space | 23375 are interpreted according to the following: 23376 0 No space separates the currency symbol and value. | 23377 1 If the currency symbol and sign string are adjacent, a space separates them from the value; | 23378 otherwise, a space separates the currency symbol from the value. | 23379 2 If the currency symbol and sign string are adjacent, a space separates them; otherwise, a | 23380 space separates the sign string from the value. | 23381 The values of p_sign_posn, n_sign_posn, int_p_sign_posn, and int_n_sign_posn are | 23382 interpreted according to the following: | 23383 0 Parentheses surround the quantity and currency_symbol or int_curr_symbol. | 23384 1 The sign string precedes the quantity and currency_symbol or int_curr_symbol. | 23385 2 The sign string succeeds the quantity and currency_symbol or int_curr_symbol. | 23386 3 The sign string immediately precedes the currency_symbol or int_curr_symbol. | 23387 4 The sign string immediately succeeds the currency_symbol or int_curr_symbol. | 23388 The implementation shall behave as if no function in this volume of IEEE Std. 1003.1-200x calls 23389 localeconv( ). 23390 CX The localeconv( ) function need not be reentrant. A function that is not required to be reentrant is 23391 not required to be thread-safe. 23392 RETURN VALUE 23393 The localeconv( ) function shall return a pointer to the filled-in object. The application shall not 23394 modify the structure pointed to by the return value which may be overwritten by a subsequent 23395 call to localeconv( ). In addition, calls to setlocale( ) with the categories LC_ALL, LC_MONETARY, 23396 or LC_NUMERIC may overwrite the contents of the structure. 23397 ERRORS 23398 No errors are defined. 23399 EXAMPLES 23400 None. 23401 APPLICATION USAGE 23402 The following table illustrates the rules which may be used by four countries to format monetary 23403 quantities. System Interfaces, Issue 6 1221 localeconv( ) System Interfaces 23404 ______________________________________________________________________ 23405 _ Country Positive Format Negative Format International Format _____________________________________________________________________ 23406 Italy L.1.230 -L.1.230 ITL.1.230 23407 Netherlands F 1.234,56 F -1.234,56 NLG 1.234,56 23408 Norway kr1.234,56 kr1.234,56- NOK 1.234,56 23409 _ Switzerland SFrs.1,234.56 SFrs.1,234.56C CHF 1,234.56 _____________________________________________________________________ 23410 For these four countries, the respective values for the monetary members of the structure 23411 returned by localeconv( ) are: ______________________________________________________________________ 23412 _ Italy Netherlands Norway Switzerland _____________________________________________________________________ 23413 int_curr_symbol "ITL." "NLG " "NOK " "CHF " 23414 currency_symbol "L." "F" "kr" "SFrs." 23415 mon_decimal_point "" "," "," "." 23416 mon_thousands_sep "." "." "." "," 23417 mon_grouping "\3" "\3" "\3" "\3" 23418 positive_sign "" "" "" "" 23419 negative_sign "-" "-" "-" "C" 23420 int_frac_digits 0 2 2 2 23421 frac_digits 0 2 2 2 23422 p_cs_precedes 1 1 1 1 23423 p_sep_by_space 0 1 0 0 23424 n_cs_precedes 1 1 1 1 23425 n_sep_by_space 0 1 0 0 23426 p_sign_posn 1 1 1 1 23427 n_sign_posn 1 4 2 2 23428 int_p_cs_precedes 1 1 1 1 23429 int_n_cs_precedes 1 1 1 1 23430 int_p_sep_by_space 0 0 0 0 23431 int_n_sep_by_space 0 0 0 0 23432 int_p_sign_posn 1 1 1 1 23433 _ int_n_sign_posn 1 4 4 2 _____________________________________________________________________ 23434 RATIONALE 23435 None. 23436 FUTURE DIRECTIONS 23437 None. 23438 SEE ALSO 23439 isalpha( ), isascii( ), nl_langinfo ( ), printf( ), scanf( ), setlocale( ), strcat( ), strchr( ), strcmp( ), strcoll( ), 23440 strcpy( ), strftime( ), strlen( ), strpbrk( ), strspn( ), strtok( ), strxfrm( ), strtod( ), the Base Definitions | 23441 volume of IEEE Std. 1003.1-200x, , | 23442 CHANGE HISTORY 23443 First released in Issue 4. Derived from the ANSI C standard. | 23444 Issue 6 23445 A note indicating that this function need not be reentrant is added to the DESCRIPTION. 23446 The RETURN VALUE section is rewritten to avoid use of the term ``must''. | 23447 This reference page is updated for alignment with the ISO/IEC 9899: 1999 standard. | 1222 Technical Standard (2000) (Draft July 31, 2000) System Interfaces localtime( ) 23448 NAME 23449 localtime, localtime_r - convert a time value to a broken-down local time 23450 SYNOPSIS 23451 #include 23452 struct tm *localtime(const time_t *timer); 23453 TSF struct tm *localtime_r(const time_t *restrict timer, | 23454 struct tm *restrict result); | 23455 | 23456 DESCRIPTION 23457 CX For localtime( ): The functionality described on this reference page is aligned with the ISO C 23458 standard. Any conflict between the requirements described here and the ISO C standard is 23459 unintentional. This volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 23460 The localtime( ) function shall convert the time in seconds since the Epoch pointed to by timer 23461 into a broken-down time, expressed as a local time. The function corrects for the timezone and 23462 any seasonal time adjustments. Local timezone information is used as though localtime( ) calls 23463 tzset( ). 23464 CX The localtime( ) function need not be reentrant. A function that is not required to be reentrant is 23465 not required to be thread-safe. 23466 TSF The localtime_r( ) function shall convert the time in seconds since the Epoch pointed to by timer | 23467 into a broken-down time stored in the structure to which result points. The localtime_r( ) function 23468 shall also return a pointer to that same structure. 23469 Unlike localtime( ), the reentrant version is not required to set tzname. 23470 RETURN VALUE 23471 The localtime( ) function shall return a pointer to the broken-down time structure. 23472 TSF Upon successful completion, localtime_r( ) shall return a pointer to the structure pointed to by 23473 the argument result. 23474 ERRORS 23475 No errors are defined. 23476 EXAMPLES 23477 Getting the Local Date and Time 23478 The following example uses the time( ) function to calculate the time elapsed, in seconds, since 23479 January 1, 1970 0:00 UTC (the Epoch), localtime( ) to convert that value to a broken-down time, 23480 and asctime( ) to convert the broken-down time values into a printable string. 23481 #include 23482 #include 23483 main() 23484 { 23485 time_t result; 23486 result = time(NULL); 23487 printf("%s%ld secs since the Epoch\n", 23488 asctime(localtime(&result)), 23489 (long)result); 23490 return(0); 23491 } System Interfaces, Issue 6 1223 localtime( ) System Interfaces 23492 This example writes the current time to stdout in a form like this: 23493 Wed Jun 26 10:32:15 1996 23494 835810335 secs since the Epoch 23495 Getting the Modification Time for a File 23496 The following example gets the modification time for a file. The localtime( ) function converts the 23497 time_t value of the last modification date, obtained by a previous call to stat( ), into a tm 23498 structure that contains the year, month, day, and so on. 23499 #include 23500 ... 23501 struct stat statbuf; 23502 ... 23503 tm = localtime(&statbuf.st_mtime); 23504 ... 23505 Timing an Event 23506 The following example gets the current time, converts it to a string using localtime( ) and 23507 asctime( ), and prints it to standard output using fputs( ). It then prints the number of minutes to 23508 an event being timed. 23509 #include 23510 #include 23511 ... 23512 time_t now; 23513 int minutes_to_event; 23514 ... 23515 time(&now); 23516 printf("The time is "); 23517 fputs(asctime(localtime(&now)), stdout); 23518 printf("There are still %d minutes to the event.\n", 23519 minutes_to_event); 23520 ... 23521 APPLICATION USAGE 23522 The asctime( ), ctime( ), getdate( ), gettimeofday( ), gmtime( ), and localtime( ) functions return values 23523 in one of two static objects: a broken-down time structure and an array of char. Execution of any 23524 of the functions may overwrite the information returned in either of these objects by any of the 23525 other functions. 23526 The localtime_r( ) function is thread-safe and shall return values in a user-supplied buffer instead 23527 of possibly using a static data area that may be overwritten by each call. 23528 RATIONALE 23529 None. 23530 FUTURE DIRECTIONS 23531 None. 23532 SEE ALSO 23533 asctime( ), clock( ), ctime( ), difftime( ), getdate( ), gettimeofday( ), gmtime( ), mktime( ), strftime( ), 23534 strptime( ), time( ), utime( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 1224 Technical Standard (2000) (Draft July 31, 2000) System Interfaces localtime( ) 23535 CHANGE HISTORY 23536 First released in Issue 1. Derived from Issue 1 of the SVID. | 23537 Issue 4 23538 The APPLICATION USAGE section is expanded to provide a more complete description of how 23539 static areas are used by the *time( ) functions. 23540 The following change is incorporated for alignment with the ISO C standard: 23541 * The timer argument is now a type const time_t. 23542 Issue 5 23543 A note indicating that the localtime( ) function need not be reentrant is added to the 23544 DESCRIPTION. 23545 The localtime_r( ) function is included for alignment with the POSIX Threads Extension. 23546 Issue 6 23547 The localtime_r( ) function is marked as part of the Thread-Safe Functions option. | 23548 Extensions beyond the ISO C standard are now marked. 23549 The APPLICATION USAGE section is updated to include a note on the thread-safe function and 23550 its avoidance of possibly using a static data area. | 23551 The restrict keyword is added to the localtime_r( ) prototype for alignment with the | 23552 ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 1225 lockf( ) System Interfaces 23553 NAME 23554 lockf - record locking on files 23555 SYNOPSIS 23556 XSI #include 23557 int lockf(int fildes, int function, off_t size); 23558 23559 DESCRIPTION 23560 The lockf( ) function allows sections of a file to be locked with advisory-mode locks. Calls to 23561 lockf( ) from other threads which attempt to lock the locked file section shall either return an 23562 error value or block until the section becomes unlocked. All the locks for a process are removed 23563 when the process terminates. Record locking with lockf( ) is supported for regular files and may 23564 be supported for other files. 23565 The fildes argument is an open file descriptor. The application shall ensure that the file descriptor 23566 has been opened with write-only permission (O_WRONLY) or with read/write permission 23567 (O_RDWR) to establish a lock with this function. 23568 The function argument is a control value which specifies the action to be taken. The permissible 23569 values for function are defined in as follows: 23570 ____________________________________________________ 23571 _ Function Description ___________________________________________________ 23572 F_ULOCK Unlock locked sections. 23573 F_LOCK Lock a section for exclusive use. 23574 F_TLOCK Test and lock a section for exclusive use. 23575 _ F_TEST Test a section for locks by other processes. ___________________________________________________ 23576 F_TEST detects if a lock by another process is present on the specified section. 23577 F_LOCK and F_TLOCK both lock a section of a file if the section is available. 23578 F_ULOCK removes locks from a section of the file. 23579 The size argument is the number of contiguous bytes to be locked or unlocked. The section to be 23580 locked or unlocked starts at the current offset in the file and extends forward for a positive size 23581 or backward for a negative size (the preceding bytes up to but not including the current offset). 23582 If size is 0, the section from the current offset through the largest possible file offset is locked 23583 (that is, from the current offset through the present or any future end-of-file). An area need not 23584 be allocated to the file to be locked because locks may exist past the end-of-file. 23585 The sections locked with F_LOCK or F_TLOCK may, in whole or in part, contain or be contained 23586 by a previously locked section for the same process. When this occurs, or if adjacent locked 23587 sections would occur, the sections are combined into a single locked section. If the request 23588 would cause the number of locks to exceed a system-imposed limit, the request shall fail. 23589 F_LOCK and F_TLOCK requests differ only by the action taken if the section is not available. 23590 F_LOCK blocks the calling thread until the section is available. F_TLOCK makes the function 23591 fail if the section is already locked by another process. 23592 File locks are released on first close by the locking process of any file descriptor for the file. 23593 F_ULOCK requests may release (wholly or in part) one or more locked sections controlled by the 23594 process. Locked sections shall be unlocked starting at the current file offset through size bytes or 23595 to the end-of-file if size is (off_t)0. When all of a locked section is not released (that is, when the 23596 beginning or end of the area to be unlocked falls within a locked section), the remaining portions 23597 of that section are still locked by the process. Releasing the center portion of a locked section 1226 Technical Standard (2000) (Draft July 31, 2000) System Interfaces lockf( ) 23598 shall cause the remaining locked beginning and end portions to become two separate locked 23599 sections. If the request would cause the number of locks in the system to exceed a system- 23600 imposed limit, the request shall fail. 23601 A potential for deadlock occurs if the threads of a process controlling a locked section are 23602 blocked by accessing another process' locked section. If the system detects that deadlock would 23603 occur, lockf( ) shall fail with an [EDEADLK] error. | 23604 The interaction between fcntl( ) and lockf( ) locks is unspecified. 23605 Blocking on a section is interrupted by any signal. 23606 An F_ULOCK request in which size is non-zero and the offset of the last byte of the requested 23607 section is the maximum value for an object of type off_t, when the process has an existing lock 23608 in which size is 0 and which includes the last byte of the requested section, shall be treated as a 23609 request to unlock from the start of the requested section with a size equal to 0. Otherwise, an 23610 F_ULOCK request shall attempt to unlock only the requested section. 23611 Attempting to lock a section of a file that is associated with a buffered stream produces 23612 unspecified results. 23613 RETURN VALUE 23614 Upon successful completion, lockf( ) shall return 0. Otherwise, it shall return -1, set errno to 23615 indicate an error, and existing locks shall not be changed. 23616 ERRORS 23617 The lockf( ) function shall fail if: 23618 [EBADF] The fildes argument is not a valid open file descriptor; or function is F_LOCK | 23619 or F_TLOCK and fildes is not a valid file descriptor open for writing. 23620 [EACCES] or [EAGAIN] | 23621 The function argument is F_TLOCK or F_TEST and the section is already 23622 locked by another process. 23623 [EDEADLK] The function argument is F_LOCK and a deadlock is detected. | 23624 [EINTR] A signal was caught during execution of the function. | 23625 [EINVAL] The function argument is not one of F_LOCK, F_TLOCK, F_TEST, or | 23626 F_ULOCK; or size plus the current file offset is less than 0. 23627 [EOVERFLOW] The offset of the first, or if size is not 0 then the last, byte in the requested | 23628 section cannot be represented correctly in an object of type off_t. 23629 The lockf( ) function may fail if: 23630 [EAGAIN] The function argument is F_LOCK or F_TLOCK and the file is mapped with | 23631 mmap( ). 23632 [EDEADLK] or [ENOLCK] | 23633 The function argument is F_LOCK, F_TLOCK, or F_ULOCK, and the request 23634 would cause the number of locks to exceed a system-imposed limit. 23635 [EOPNOTSUPP] or [EINVAL] | 23636 The implementation does not support the locking of files of the type indicated 23637 by the fildes argument. System Interfaces, Issue 6 1227 lockf( ) System Interfaces 23638 EXAMPLES 23639 Locking a Portion of a File 23640 In the following example, a file named /home/cnd/mod1 is being modified. Other processes that 23641 use locking are prevented from changing it during this process. Only the first 10,000 bytes are 23642 locked, and the lock call fails if another process has any part of this area locked already. 23643 #include 23644 #include 23645 int fildes; 23646 int status; 23647 ... 23648 fildes = open("/home/cnd/mod1", O_RDWR); 23649 status = lockf(fildes, F_TLOCK, (off_t)10000); 23650 APPLICATION USAGE 23651 Record-locking should not be used in combination with the fopen( ), fread( ), fwrite( ), and other 23652 stdio functions. Instead, the more primitive, non-buffered functions (such as open( )) should be 23653 used. Unexpected results may occur in processes that do buffering in the user address space. The 23654 process may later read/write data which is/was locked. The stdio functions are the most 23655 common source of unexpected buffering. 23656 The alarm( ) function may be used to provide a timeout facility in applications requiring it. 23657 RATIONALE 23658 None. 23659 FUTURE DIRECTIONS 23660 None. 23661 SEE ALSO 23662 alarm( ), chmod( ), close( ), creat( ), fcntl( ), fopen( ), mmap( ), open( ), read( ), write( ), the Base | 23663 Definitions volume of IEEE Std. 1003.1-200x, | 23664 CHANGE HISTORY 23665 First released in Issue 4, Version 2. 23666 Issue 5 23667 Moved from X/OPEN UNIX extension to BASE. 23668 Large File Summit extensions are added. In particular, the description of [EINVAL] is clarified 23669 and moved from optional to mandatory status. 23670 A note is added to the DESCRIPTION indicating the effects of attempting to lock a section of a 23671 file that is associated with a buffered stream. 23672 Issue 6 23673 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 1228 Technical Standard (2000) (Draft July 31, 2000) System Interfaces log( ) 23674 NAME 23675 log, logf, logl - natural logarithm function | 23676 SYNOPSIS 23677 #include 23678 double log(double x); 23679 float logf(float x); | 23680 long double logl(long double x); | 23681 DESCRIPTION | 23682 CX The functionality described on this reference page is aligned with the ISO C standard. Any 23683 conflict between the requirements described here and the ISO C standard is unintentional. This 23684 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 23685 These functions shall compute the natural logarithm of x, loge(x). The application shall ensure | 23686 that the value of x is positive. 23687 An application wishing to check for error situations should set errno to 0 before calling log( ). If 23688 errno is non-zero on return, or the return value is NaN, an error has occurred. 23689 RETURN VALUE 23690 Upon successful completion, these functions shall return the natural logarithm of x. | 23691 XSI If x is NaN, NaN shall be returned and errno may be set to [EDOM]. | 23692 XSI If x is less than 0, -HUGE_VAL or NaN shall be returned,and errno shall be set to [EDOM]. 23693 If x is 0, -HUGE_VAL shall be returned and errno may be set to [ERANGE]. | 23694 ERRORS 23695 These functions shall fail if: | 23696 [EDOM] The value of x is negative. | 23697 These functions may fail if: | 23698 XSI [EDOM] The value of x is NaN. | 23699 [ERANGE] The value of x is 0. | 23700 XSI No other errors shall occur. 23701 EXAMPLES 23702 None. 23703 APPLICATION USAGE 23704 None. 23705 RATIONALE 23706 None. 23707 FUTURE DIRECTIONS 23708 None. 23709 SEE ALSO 23710 exp( ), isnan( ), log10( ), log1p( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 23711 CHANGE HISTORY 23712 First released in Issue 1. Derived from Issue 1 of the SVID. | System Interfaces, Issue 6 1229 log( ) System Interfaces 23713 Issue 4 23714 References to matherr( ) are removed. 23715 The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 23716 ISO C standard and to rationalize error handling in the mathematics functions. 23717 The return value specified for [EDOM] is marked as an extension. 23718 Issue 5 23719 The DESCRIPTION is updated to indicate how an application should check for an error. This 23720 text was previously published in the APPLICATION USAGE section. 23721 Issue 6 23722 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. | 23723 The logf( ) and logl( ) functions are added for alignment with the ISO/IEC 9899: 1999 standard. | 1230 Technical Standard (2000) (Draft July 31, 2000) System Interfaces log10( ) 23724 NAME 23725 log10, log10f, log10l - base 10 logarithm function | 23726 SYNOPSIS 23727 #include 23728 double log10(double x); 23729 float log10f(float x); | 23730 long double log10l(long double x); | 23731 DESCRIPTION | 23732 CX The functionality described on this reference page is aligned with the ISO C standard. Any 23733 conflict between the requirements described here and the ISO C standard is unintentional. This 23734 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 23735 These functions shall compute the base 10 logarithm of x, log (x). The application shall ensure | 10 23736 that the value of x is positive. 23737 An application wishing to check for error situations should set errno to 0 before calling log10( ). 23738 If errno is non-zero on return, or the return value is NaN, an error has occurred. 23739 RETURN VALUE 23740 Upon successful completion, these functions shall return the base 10 logarithm of x. | 23741 XSI If x is NaN, NaN shall be returned and errno may be set to [EDOM]. | 23742 XSI If x is less than 0, -HUGE_VAL or NaN shall be returned,and errno shall be set to [EDOM]. 23743 If x is 0, -HUGE_VAL shall be returned and errno may be set to [ERANGE]. | 23744 ERRORS 23745 These functions shall fail if: | 23746 [EDOM] The value of x is negative. | 23747 These functions may fail if: | 23748 XSI [EDOM] The value of x is NaN. | 23749 [ERANGE] The value of x is 0. | 23750 XSI No other errors shall occur. 23751 EXAMPLES 23752 None. 23753 APPLICATION USAGE 23754 None. 23755 RATIONALE 23756 None. 23757 FUTURE DIRECTIONS 23758 None. 23759 SEE ALSO 23760 isnan( ), log( ), pow( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 23761 CHANGE HISTORY 23762 First released in Issue 1. Derived from Issue 1 of the SVID. | System Interfaces, Issue 6 1231 log10( ) System Interfaces 23763 Issue 4 23764 References to matherr( ) are removed. 23765 The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 23766 ISO C standard and to rationalize error handling in the mathematics functions. 23767 The return value specified for [EDOM] is marked as an extension. 23768 Issue 5 23769 The DESCRIPTION is updated to indicate how an application should check for an error. This 23770 text was previously published in the APPLICATION USAGE section. 23771 Issue 6 23772 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. | 23773 The log10f( ) and log10l( ) functions are added for alignment with the ISO/IEC 9899: 1999 | 23774 standard. | 1232 Technical Standard (2000) (Draft July 31, 2000) System Interfaces log1p( ) 23775 NAME 23776 log1p, log1pf, log1pl - compute a natural logarithm | 23777 SYNOPSIS 23778 #include | 23779 double log1p(double x); | 23780 float log1pf(float x); | 23781 long double log1pl(long double x); | 23782 DESCRIPTION | 23783 These functions shall compute log (1.0 + x). The application shall ensure that the value of x is | e 23784 greater than -1.0. 23785 RETURN VALUE 23786 Upon successful completion, these functions shall return the natural logarithm of 1.0 + x. | 23787 If x is NaN, log1p( ) shall return NaN and may set errno to [EDOM]. | 23788 If x is less than -1.0, log1p( ) shall return -HUGE_VAL or NaN and set errno to [EDOM]. 23789 If x is -1.0, log1p( ) shall return -HUGE_VAL and may set errno to [ERANGE]. | 23790 ERRORS 23791 These functions shall fail if: | 23792 [EDOM] The value of x is less than -1.0. | 23793 These functions may fail and set errno to: | 23794 [EDOM] The value of x is NaN. | 23795 [ERANGE] The value of x is -1.0. | 23796 No other errors shall occur. 23797 EXAMPLES 23798 None. 23799 APPLICATION USAGE 23800 None. 23801 RATIONALE 23802 None. 23803 FUTURE DIRECTIONS 23804 None. 23805 SEE ALSO 23806 log( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 23807 CHANGE HISTORY 23808 First released in Issue 4, Version 2. 23809 Issue 5 23810 Moved from X/OPEN UNIX extension to BASE. 23811 Issue 6 23812 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. | 23813 The log1pf( ) and log1pl( ) functions are added for alignment with the ISO/IEC 9899: 1999 || 23814 standard. | System Interfaces, Issue 6 1233 log2( ) System Interfaces 23815 NAME | 23816 log2, log2f, log2l - compute base 2 logarithm functions | 23817 SYNOPSIS | 23818 #include | 23819 double log2(double x); | 23820 float log2f(float x); | 23821 long double log2l(long double x); | 23822 DESCRIPTION | 23823 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 23824 conflict between the requirements described here and the ISO C standard is unintentional. This | 23825 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 23826 These functions shall compute the base 2 logarithm of x, log2(x). The application shall ensure | 23827 that the value of x is positive. | 23828 An application wishing to check for error situations should set errno to 0 before calling these | 23829 functions. If errno is non-zero on return, or the return value is NaN, an error has occurred. | 23830 RETURN VALUE | 23831 Upon successful completion, these functions shall return the base 2 logarithm of x. | 23832 If x is NaN, these functions shall return NaN and may set errno to [EDOM]. | 23833 If x is less than 0, these functions shall return -HUGE_VAL or NaN and set errno to [EDOM]. | 23834 If x is 0, these functions shall return -HUGE_VAL and may set errno to [ERANGE]. | 23835 ERRORS | 23836 These functions shall fail if: | 23837 [EDOM] The value of x is less than 0. | 23838 These functions may fail if: | 23839 [EDOM] The value of x is NaN. | 23840 [ERANGE] The value of x is 0. | 23841 No other errors shall occur. | 23842 EXAMPLES | 23843 None. | 23844 APPLICATION USAGE | 23845 None. | 23846 RATIONALE | 23847 None. | 23848 FUTURE DIRECTIONS | 23849 None. | 23850 SEE ALSO | 23851 log( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 23852 CHANGE HISTORY || 23853 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | 1234 Technical Standard (2000) (Draft July 31, 2000) System Interfaces logb( ) 23854 NAME 23855 logb, logbf, logbl - radix-independent exponent | 23856 SYNOPSIS 23857 XSI #include 23858 double logb(double x); 23859 float logbf(float x); | 23860 long double logbl(long double x); | 23861 | 23862 DESCRIPTION 23863 These functions shall compute the exponent of x, which is the integral part of logr x , as a | 23864 signed floating point value, for non-zero x, where r is the radix of the machine's floating-point | 23865 arithmetic, which is the value of FLT_RADIX defined in the header. | 23866 RETURN VALUE 23867 Upon successful completion, these functions shall return the exponent of x. | 23868 If x is 0.0, logb( ) shall return -HUGE_VAL and set errno to [EDOM]. 23869 If x is ±Inf, logb( ) shall return +Inf. 23870 If x is NaN, logb( ) shall return NaN and may set errno to [EDOM]. | 23871 ERRORS 23872 These functions shall fail if: | 23873 [EDOM] The x argument is 0.0. | 23874 These functions may fail if: | 23875 [EDOM] The x argument is NaN. | 23876 EXAMPLES 23877 None. 23878 APPLICATION USAGE 23879 None. 23880 RATIONALE 23881 None. 23882 FUTURE DIRECTIONS 23883 None. 23884 SEE ALSO 23885 ilogb( ), scalb( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 23886 CHANGE HISTORY 23887 First released in Issue 4, Version 2. 23888 Issue 5 23889 Moved from X/OPEN UNIX extension to BASE. | 23890 Issue 6 | 23891 The logbf( ) and logbl( ) functions are added for alignment with the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 1235 longjmp( ) System Interfaces 23892 NAME 23893 longjmp - non-local goto 23894 SYNOPSIS 23895 #include 23896 void longjmp(jmp_buf env, int val); 23897 DESCRIPTION 23898 CX The functionality described on this reference page is aligned with the ISO C standard. Any 23899 conflict between the requirements described here and the ISO C standard is unintentional. This 23900 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 23901 The longjmp( ) function shall restore the environment saved by the most recent invocation of 23902 setjmp( ) in the same thread, with the corresponding jmp_buf argument. If there is no such | 23903 invocation, or if the function containing the invocation of the setjmp( ) macro has terminated | 23904 execution in the interim, or if the invocation of setjmp( ) was within the scope of an identifier | 23905 with variably modified type and execution has left that scope in the interim, the behavior is | 23906 CX undefined. It is unspecified whether longjmp( ) restores the signal mask, leaves the signal mask | 23907 unchanged, or restores it to its value at the time setjmp( ) was called. 23908 All accessible objects have values as of the time longjmp( ) was called, and all other components | 23909 of the abstract machine have state (for example, floating-point status flags and open files), | 23910 except that the values of objects of automatic storage duration are indeterminate if they meet all | 23911 the following conditions: | 23912 * They are local to the function containing the corresponding setjmp( ) invocation. 23913 * They do not have volatile-qualified type. 23914 * They are changed between the setjmp( ) invocation and longjmp( ) call. 23915 As it bypasses the usual function call and return mechanisms, longjmp( ) shall execute correctly 23916 in contexts of interrupts, signals, and any of their associated functions. However, if longjmp( ) is 23917 invoked from a nested signal handler (that is, from a function invoked as a result of a signal 23918 raised during the handling of another signal), the behavior is undefined. 23919 CX The effect of a call to longjmp( ) where initialization of the jmp_buf structure was not performed 23920 in the calling thread is undefined. 23921 RETURN VALUE 23922 After longjmp( ) is completed, program execution continues as if the corresponding invocation of 23923 setjmp( ) had just returned the value specified by val. The longjmp( ) function shall not cause 23924 setjmp( ) to return 0; if val is 0, setjmp( ) shall return 1. 23925 ERRORS 23926 No errors are defined. 23927 EXAMPLES 23928 None. 23929 APPLICATION USAGE 23930 Applications whose behavior depends on the value of the signal mask should not use longjmp( ) 23931 and setjmp( ), since their effect on the signal mask is unspecified, but should instead use the 23932 siglongjmp( ) and sigsetjmp( ) functions (which can save and restore the signal mask under 23933 application control). 1236 Technical Standard (2000) (Draft July 31, 2000) System Interfaces longjmp( ) 23934 RATIONALE 23935 None. 23936 FUTURE DIRECTIONS 23937 None. 23938 SEE ALSO 23939 setjmp( ), sigaction( ), siglongjmp( ), sigsetjmp( ), the Base Definitions volume of | 23940 IEEE Std. 1003.1-200x, | 23941 CHANGE HISTORY 23942 First released in Issue 1. Derived from Issue 1 of the SVID. | 23943 Issue 4 23944 The APPLICATION USAGE section is deleted. 23945 The following change is incorporated for alignment with the ISO C standard: 23946 * Mention of volatile-qualified types is added to the DESCRIPTION. 23947 Issue 4, Version 2 23948 The DESCRIPTION is updated for X/OPEN UNIX conformance and discusses valid possibilities 23949 for the resulting state of the signal mask. 23950 Issue 5 23951 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 23952 Issue 6 23953 Extensions beyond the ISO C standard are now marked. 23954 The following new requirements on POSIX implementations derive from alignment with the 23955 Single UNIX Specification: 23956 * The DESCRIPTION now explicitly makes longjmp( )'s effect on the signal mask unspecified. 23957 The DESCRIPTION is updated for alignment with the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 1237 lrand48( ) System Interfaces 23958 NAME 23959 lrand48 - generate uniformly distributed pseudo-random non-negative long integers 23960 SYNOPSIS 23961 XSI #include 23962 long lrand48(void); | 23963 | 23964 DESCRIPTION 23965 Refer to drand48( ). 1238 Technical Standard (2000) (Draft July 31, 2000) System Interfaces lsearch( ) 23966 NAME 23967 lsearch, lfind - linear search and update 23968 SYNOPSIS 23969 XSI #include 23970 void *lsearch(const void *key, void *base, size_t *nelp, size_t width, 23971 int (*compar)(const void *, const void *)); 23972 void *lfind(const void *key, const void *base, size_t *nelp, 23973 size_t width, int (*compar)(const void *, const void *)); 23974 23975 DESCRIPTION 23976 The lsearch( ) function is a linear search routine. It returns a pointer into the table for the 23977 matching entry. If the entry does not occur, it is added at the end of the table. The key argument 23978 points to the entry to be sought in the table. The base argument points to the first element in the 23979 table. The width argument is the size of an element in bytes. The nelp argument points to an 23980 integer containing the current number of elements in the table. The integer to which nelp points 23981 is incremented if the entry is added to the table. The compar argument points to a comparison 23982 function which the application shall supply (for example, strcmp( )). It is called with two 23983 arguments that point to the elements being compared. The application shall ensure that the 23984 function returns 0 if the elements are equal, and non-zero otherwise. 23985 The lfind( ) function is the same as lsearch( ) except that if the entry is not found, it is not added to 23986 the table. Instead, a null pointer is returned. 23987 RETURN VALUE 23988 If the searched for entry is found, both lsearch( ) and lfind( ) shall return a pointer to it. Otherwise, 23989 lfind( ) shall return a null pointer and lsearch( ) shall return a pointer to the newly added element. 23990 Both functions shall return a null pointer in case of error. 23991 ERRORS 23992 No errors are defined. 23993 EXAMPLES 23994 Storing Strings in a Table 23995 This fragment reads in less than or equal to TABSIZE strings of length less than or equal to 23996 ELSIZE and stores them in a table, eliminating duplicates. 23997 #include 23998 #include 23999 #include 24000 #define TABSIZE 50 24001 #define ELSIZE 120 24002 ... 24003 char line[ELSIZE], tab[TABSIZE][ELSIZE]; 24004 size_t nel = 0; 24005 ... 24006 while (fgets(line, ELSIZE, stdin) != NULL && nel < TABSIZE) 24007 (void) lsearch(line, tab, &nel, 24008 ELSIZE, (int (*)(const void *, const void *)) strcmp); 24009 ... System Interfaces, Issue 6 1239 lsearch( ) System Interfaces 24010 Finding a Matching Entry 24011 The following example finds any line that reads "This is a test.". 24012 #include 24013 #include 24014 ... 24015 char line[ELSIZE], tab[TABSIZE][ELSIZE]; 24016 size_t nel = 0; 24017 char *findline; 24018 void *entry; 24019 findline = "This is a test.\n"; 24020 entry = lfind(findline, tab, &nel, ELSIZE, ( 24021 int (*)(const void *, const void *)) strcmp); 24022 APPLICATION USAGE 24023 The comparison function need not compare every byte, so arbitrary data may be contained in 24024 the elements in addition to the values being compared. 24025 Undefined results can occur if there is not enough room in the table to add a new item. 24026 RATIONALE 24027 None. 24028 FUTURE DIRECTIONS 24029 None. 24030 SEE ALSO 24031 hcreate( ), tsearch( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 24032 CHANGE HISTORY 24033 First released in Issue 1. Derived from Issue 1 of the SVID. | 24034 Issue 4 24035 In the SYNOPSIS section, the type of argument key in the declaration of lsearch( ) is changed from 24036 void* to const void*, the type arguments key and base have been changed from void* to const 24037 void* in the declaration of lfind( ), and the arguments to compar are defined for both functions. 24038 In the EXAMPLES section, the sample code is updated to use ISO C standard syntax. 24039 Warnings about the casting of various arguments are removed from the APPLICATION USAGE 24040 section, as casting requirements are now clear from the function definitions. 24041 Issue 6 24042 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 1240 Technical Standard (2000) (Draft July 31, 2000) System Interfaces lseek( ) 24043 NAME 24044 lseek - move the read/write file offset 24045 SYNOPSIS 24046 #include 24047 off_t lseek(int fildes, off_t offset, int whence); 24048 DESCRIPTION 24049 The lseek( ) function shall set the file offset for the open file description associated with the file 24050 descriptor fildes, as follows: 24051 * If whence is {SEEK_SET}, the file offset is set to offset bytes. 24052 * If whence is {SEEK_CUR}, the file offset is set to its current location plus offset. 24053 * If whence is {SEEK_END}, the file offset is set to the size of the file plus offset. 24054 The symbolic constants {SEEK_SET}, {SEEK_CUR}, and {SEEK_END} are defined in . 24055 The behavior of lseek( ) on devices which are incapable of seeking is implementation-defined. | 24056 The value of the file offset associated with such a device is undefined. 24057 The lseek( ) function shall allow the file offset to be set beyond the end of the existing data in the 24058 file. If data is later written at this point, subsequent reads of data in the gap shall return bytes 24059 with the value 0 until data is actually written into the gap. 24060 The lseek( ) function shall not, by itself, extend the size of a file. 24061 SHM If fildes refers to a shared memory object, the result of the lseek( ) function is unspecified. 24062 TYM If fildes refers to a typed memory object, the result of the lseek( ) function is unspecified. 24063 RETURN VALUE 24064 Upon successful completion, the resulting offset, as measured in bytes from the beginning of the 24065 file, shall be returned. Otherwise, (off_t)-1 shall be returned, errno shall be set to indicate the 24066 error, and the file offset shall remain unchanged. 24067 ERRORS 24068 The lseek( ) function shall fail if: 24069 [EBADF] The fildes argument is not an open file descriptor. | 24070 [EINVAL] The whence argument is not a proper value, or the resulting file offset would | 24071 be negative for a regular file, block special file, or directory. | 24072 [EOVERFLOW] The resulting file offset would be a value which cannot be represented | 24073 correctly in an object of type off_t. | 24074 [ESPIPE] The fildes argument is associated with a pipe, FIFO, or socket. | 24075 EXAMPLES 24076 None. 24077 APPLICATION USAGE 24078 None. 24079 RATIONALE 24080 The ISO C standard includes the functions fgetpos( ) and fsetpos( ), which work on very large files 24081 by use of a special positioning type. 24082 Although lseek( ) may position the file offset beyond the end of the file, this function does not 24083 itself extend the size of the file. While the only function in this volume of IEEE Std. 1003.1-200x System Interfaces, Issue 6 1241 lseek( ) System Interfaces 24084 that may directly extend the size of the file is write( ), several functions originally derived from 24085 the ISO C standard, such as fwrite( ), fprintf( ), and so on, may do so (by causing calls on write( )). 24086 An invalid file offset that would cause [EINVAL] to be returned may be both implementation- | 24087 defined and device-dependent (for example, memory may have few invalid values). A negative | 24088 file offset may be valid for some devices in some implementations. 24089 The POSIX.1-1990 standard did not specifically prohibit lseek( ) from returning a negative offset. 24090 Therefore, an application was required to clear errno prior to the call and check errno upon return 24091 to determine whether a return value of (off_t)-1 is a negative offset or an indication of an error 24092 condition. The standard developers did not wish to require this action on the part of a portable 24093 application, and chose to require that errno be set to [EINVAL] when the resulting file offset 24094 would be negative for a regular file, block special file, or directory. 24095 FUTURE DIRECTIONS 24096 None. 24097 SEE ALSO 24098 open( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , | 24099 CHANGE HISTORY 24100 First released in Issue 1. Derived from Issue 1 of the SVID. | 24101 Issue 4 24102 The header is now marked as optional (OH); this header need not be included on 24103 XSI-conformant systems. 24104 The APPLICATION USAGE section is removed, as the ISO POSIX-1 standard now requires that 24105 off_t be signed. 24106 Issue 5 24107 The DESCRIPTION is updated for alignment with the POSIX Realtime Extension. 24108 Large File Summit extensions are added. 24109 Issue 6 24110 In the SYNOPSIS, the inclusion of is no longer required. 24111 The following new requirements on POSIX implementations derive from alignment with the 24112 Single UNIX Specification: 24113 * The requirement to include has been removed. Although was 24114 required for conforming implementations of previous POSIX specifications, it was not 24115 required for UNIX applications. 24116 * The [EOVERFLOW] error condition is added. This change is to support large files. 24117 An additional [ESPIPE] error condition is added for sockets. 24118 The DESCRIPTION is updated for alignment with IEEE Std. 1003.1j-2000 by specifying that 24119 lseek( ) results are unspecified for typed memory objects. 1242 Technical Standard (2000) (Draft July 31, 2000) System Interfaces lstat( ) 24120 NAME 24121 lstat - get symbolic link status 24122 SYNOPSIS 24123 #include 24124 int lstat(const char *restrict path, struct stat *restrict buf); | 24125 DESCRIPTION | 24126 The lstat( ) function shall have the same effect as stat( ), except when path refers to a symbolic 24127 link. In that case lstat( ) shall return information about the link, while stat( ) shall return 24128 information about the file the link references. 24129 For symbolic links, the st_mode member shall contain meaningful information when used with 24130 the file type macros, and the st_size member shall contain the length of the path name contained 24131 in the symbolic link. File mode bits and the contents of the remaining members of the stat 24132 structure are unspecified. The value returned in the st_size member is the length of the contents 24133 of the symbolic link, and does not count any trailing null. 24134 RETURN VALUE 24135 Upon successful completion, lstat( ) shall return 0. Otherwise, it shall return -1 and set errno to 24136 indicate the error. 24137 ERRORS 24138 The lstat( ) function shall fail if: 24139 [EACCES] A component of the path prefix denies search permission. 24140 [EIO] An error occurred while reading from the file system. 24141 [ELOOP] A loop exists in symbolic links encountered during resolution of the path 24142 argument. 24143 [ENAMETOOLONG] | 24144 The length of a path name exceeds {PATH_MAX} or a path name component | 24145 is longer than {NAME_MAX}. | 24146 [ENOTDIR] A component of the path prefix is not a directory. | 24147 [ENOENT] A component of path does not name an existing file or path is an empty string. | 24148 [EOVERFLOW] The file size in bytes or the number of blocks allocated to the file or the file | 24149 serial number cannot be represented correctly in the structure pointed to by 24150 buf. 24151 The lstat( ) function may fail if: 24152 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 24153 resolution of the path argument. 24154 [ENAMETOOLONG] | 24155 As a result of encountering a symbolic link in resolution of the path argument, 24156 the length of the substituted path name string exceeded {PATH_MAX}. 24157 [EOVERFLOW] One of the members is too large to store into the structure pointed to by the | 24158 buf argument. System Interfaces, Issue 6 1243 lstat( ) System Interfaces 24159 EXAMPLES 24160 Obtaining Symbolic Link Status Information 24161 The following example shows how to obtain status information for a symbolic link named 24162 /modules/pass1. The structure variable buffer is defined for the stat structure. If the path 24163 argument specified the file name for the file pointed to by the symbolic link (/home/cnd/mod1), 24164 the results of calling the function would be the same as those returned by a call to the stat( ) 24165 function. 24166 #include 24167 struct stat buffer; 24168 int status; 24169 ... 24170 status = lstat("/modules/pass1", &buffer); 24171 APPLICATION USAGE 24172 None. 24173 RATIONALE 24174 The lstat( ) function is not required to update the time-related fields if the named file is not a 24175 symbolic link. While the st_uid, st_gid, st_atime, st_mtime, and st_ctime members of the stat 24176 structure may apply to a symbolic link, they are not required to do so. No functions in 24177 IEEE Std. 1003.1-200x are required to maintain any of these time fields. 24178 FUTURE DIRECTIONS 24179 None. 24180 SEE ALSO 24181 fstat( ), readlink( ), stat( ), symlink( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 24182 24183 CHANGE HISTORY 24184 First released in Issue 4, Version 2. 24185 Issue 5 24186 Moved from X/OPEN UNIX extension to BASE. 24187 Large File Summit extensions are added. 24188 Issue 6 24189 The following changes were made to align with the IEEE P1003.1a draft standard: 24190 * This function is now mandatory. 24191 * The [ELOOP] optional error condition is added. 24192 The restrict keyword is added to the lstat( ) prototype for alignment with the ISO/IEC 9899: 1999 | 24193 standard. | 1244 Technical Standard (2000) (Draft July 31, 2000) System Interfaces makecontext( ) 24194 NAME 24195 makecontext, swapcontext - manipulate user contexts 24196 SYNOPSIS 24197 XSI #include 24198 void makecontext(ucontext_t *ucp, void (*func)(void), | 24199 int argc, ...); | 24200 int swapcontext(ucontext_t *restrict oucp, | 24201 const ucontext_t *restrict ucp); | 24202 | 24203 DESCRIPTION 24204 The makecontext( ) function shall modify the context specified by ucp, which has been initialized 24205 using getcontext( ). When this context is resumed using swapcontext( ) or setcontext( ), program 24206 execution shall continue by calling func, passing it the arguments that follow argc in the 24207 makecontext( ) call. 24208 Before a call is made to makecontext( ), the application shall ensure that the context being 24209 modified has a stack allocated for it. The application shall ensure that the value of argc matches 24210 the number of integer arguments passed to func; otherwise, the behavior is undefined. 24211 The uc_link member is used to determine the context that shall be resumed when the context 24212 being modified by makecontext( ) returns. The application shall ensure that the uc_link member is 24213 initialized prior to the call to makecontext( ). 24214 The swapcontext( ) function shall save the current context in the context structure pointed to by 24215 oucp and shall set the context to the context structure pointed to by ucp. 24216 RETURN VALUE 24217 Upon successful completion, swapcontext( ) shall return 0. Otherwise, -1 shall be returned and 24218 errno set to indicate the error. 24219 ERRORS 24220 The swapcontext( ) function shall fail if: 24221 [ENOMEM] The ucp argument does not have enough stack left to complete the operation. | 24222 EXAMPLES 24223 None. 24224 APPLICATION USAGE 24225 None. 24226 RATIONALE 24227 None. 24228 FUTURE DIRECTIONS 24229 None. 24230 SEE ALSO 24231 exit( ), getcontext( ), sigaction( ), sigprocmask( ), the Base Definitions volume of | 24232 IEEE Std. 1003.1-200x, | 24233 CHANGE HISTORY 24234 First released in Issue 4, Version 2. System Interfaces, Issue 6 1245 makecontext( ) System Interfaces 24235 Issue 5 24236 Moved from X/OPEN UNIX extension to BASE. 24237 In the ERRORS section, the description of [ENOMEM] is changed to apply to swapcontext( ) only. 24238 Issue 6 24239 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. | 24240 The restrict keyword is added to the swapcontext( ) prototype for alignment with the | 24241 ISO/IEC 9899: 1999 standard. | 1246 Technical Standard (2000) (Draft July 31, 2000) System Interfaces malloc( ) 24242 NAME 24243 malloc - a memory allocator 24244 SYNOPSIS 24245 #include 24246 void *malloc(size_t size); 24247 DESCRIPTION 24248 CX The functionality described on this reference page is aligned with the ISO C standard. Any 24249 conflict between the requirements described here and the ISO C standard is unintentional. This 24250 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 24251 The malloc( ) function shall allocate unused space for an object whose size in bytes is specified by 24252 size and whose value is indeterminate. 24253 The order and contiguity of storage allocated by successive calls to malloc( ) is unspecified. The | 24254 pointer returned if the allocation succeeds shall be suitably aligned so that it may be assigned to | 24255 a pointer to any type of object and then used to access such an object in the space allocated (until | 24256 the space is explicitly freed or reallocated). Each such allocation shall yield a pointer to an object 24257 disjoint from any other object. The pointer returned points to the start (lowest byte address) of 24258 the allocated space. If the space cannot be allocated, a null pointer shall be returned. If the size of | 24259 the space requested is 0, the behavior is implementation-defined; the value returned shall be | 24260 either a null pointer or a unique pointer. | 24261 RETURN VALUE 24262 Upon successful completion with size not equal to 0, malloc( ) shall return a pointer to the 24263 allocated space. If size is 0, either a null pointer or a unique pointer that can be successfully 24264 CX passed to free( ) shall be returned. Otherwise, it shall return a null pointer and set errno to 24265 indicate the error. 24266 ERRORS 24267 The malloc( ) function shall fail if: 24268 CX [ENOMEM] Insufficient storage space is available. | 24269 EXAMPLES 24270 None. 24271 APPLICATION USAGE 24272 None. 24273 RATIONALE 24274 None. 24275 FUTURE DIRECTIONS 24276 None. 24277 SEE ALSO 24278 calloc( ), free( ), realloc( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 24279 CHANGE HISTORY 24280 First released in Issue 1. Derived from Issue 1 of the SVID. | 24281 Issue 4 24282 The setting of errno and the [ENOMEM] error are marked as extensions. 24283 The APPLICATION USAGE section is changed to record that need no longer be 24284 supported on XSI-conformant systems. System Interfaces, Issue 6 1247 malloc( ) System Interfaces 24285 The following change is incorporated for alignment with the ISO C standard: 24286 * The RETURN VALUE section is updated to indicate what is returned if size is 0. 24287 Issue 6 24288 Extensions beyond the ISO C standard are now marked. 24289 The following new requirements on POSIX implementations derive from alignment with the 24290 Single UNIX Specification: 24291 * In the RETURN VALUE section, the requirement to set errno to indicate an error is added. 24292 * The [ENOMEM] error condition is added. 1248 Technical Standard (2000) (Draft July 31, 2000) System Interfaces mblen( ) 24293 NAME 24294 mblen - get number of bytes in a character 24295 SYNOPSIS 24296 #include 24297 int mblen(const char *s, size_t n); 24298 DESCRIPTION 24299 CX The functionality described on this reference page is aligned with the ISO C standard. Any 24300 conflict between the requirements described here and the ISO C standard is unintentional. This 24301 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 24302 If s is not a null pointer, mblen( ) determines the number of bytes constituting the character 24303 pointed to by s. Except that the shift state of mbtowc( ) is not affected, it is equivalent to: 24304 mbtowc((wchar_t *)0, s, n); 24305 The implementation shall behave as if no function defined in this volume of 24306 IEEE Std. 1003.1-200x calls mblen( ). 24307 The behavior of this function is affected by the LC_CTYPE category of the current locale. For a 24308 state-dependent encoding, this function is placed into its initial state by a call for which its 24309 character pointer argument, s, is a null pointer. Subsequent calls with s as other than a null 24310 pointer cause the internal state of the function to be altered as necessary. A call with s as a null 24311 pointer causes this function to return a non-zero value if encodings have state dependency, and 24312 0 otherwise. If the implementation employs special bytes to change the shift state, these bytes do 24313 not produce separate wide-character codes, but are grouped with an adjacent character. 24314 Changing the LC_CTYPE category causes the shift state of this function to be indeterminate. 24315 RETURN VALUE 24316 If s is a null pointer, mblen( ) shall return a non-zero or 0 value, if character encodings, 24317 respectively, do or do not have state-dependent encodings. If s is not a null pointer, mblen( ) shall 24318 either return 0 (if s points to the null byte), or return the number of bytes that constitute the 24319 character (if the next n or fewer bytes form a valid character), or return -1 (if they do not form a 24320 CX valid character) and may set errno to indicate the error. In no case shall the value returned be 24321 greater than n or the value of the {MB_CUR_MAX} macro. 24322 ERRORS 24323 The mblen( ) function may fail if: 24324 XSI [EILSEQ] Invalid character sequence is detected. | 24325 EXAMPLES 24326 None. 24327 APPLICATION USAGE 24328 None. 24329 RATIONALE 24330 None. 24331 FUTURE DIRECTIONS 24332 None. 24333 SEE ALSO 24334 mbtowc( ), mbstowcs( ), wctomb( ), wcstombs( ), the Base Definitions volume of | 24335 IEEE Std. 1003.1-200x, | System Interfaces, Issue 6 1249 mblen( ) System Interfaces 24336 CHANGE HISTORY 24337 First released in Issue 4. Aligned with the ISO C standard. | 1250 Technical Standard (2000) (Draft July 31, 2000) System Interfaces mbrlen( ) 24338 NAME 24339 mbrlen - get number of bytes in a character (restartable) 24340 SYNOPSIS 24341 #include 24342 size_t mbrlen(const char *restrict s, size_t n, | 24343 mbstate_t *restrict ps); | 24344 DESCRIPTION | 24345 CX The functionality described on this reference page is aligned with the ISO C standard. Any 24346 conflict between the requirements described here and the ISO C standard is unintentional. This 24347 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 24348 If s is not a null pointer, mbrlen( ) shall determine the number of bytes constituting the character 24349 pointed to by s. It is equivalent to: 24350 mbstate_t internal; 24351 mbrtowc(NULL, s, n, ps != NULL ? ps : &internal); 24352 If ps is a null pointer, the mbrlen( ) function uses its own internal mbstate_t object, which is 24353 initialized at program start-up to the initial conversion state. Otherwise, the mbstate_t object 24354 pointed to by ps is used to completely describe the current conversion state of the associated 24355 character sequence. The implementation shall behave as if no function defined in this volume of 24356 IEEE Std. 1003.1-200x calls mbrlen( ). 24357 XSI The behavior of this function is affected by the LC_CTYPE category of the current locale. 24358 RETURN VALUE 24359 The mbrlen( ) function shall return the first of the following that applies: 24360 0 If the next n or fewer bytes complete the character that corresponds to the null 24361 wide character. 24362 positive If the next n or fewer bytes complete a valid character; the value returned shall 24363 be the number of bytes that complete the character. 24364 (size_t)-2 If the next n bytes contribute to an incomplete but potentially valid character, 24365 and all n bytes have been processed. When n has at least the value of the 24366 {MB_CUR_MAX} macro, this case can only occur if s points at a sequence of 24367 redundant shift sequences (for implementations with state-dependent 24368 encodings). 24369 (size_t)-1 If an encoding error occurs, in which case the next n or fewer bytes do not 24370 contribute to a complete and valid character. In this case, [EILSEQ] shall be | 24371 stored in errno and the conversion state is undefined. 24372 ERRORS 24373 The mbrlen( ) function may fail if: 24374 [EINVAL] ps points to an object that contains an invalid conversion state. | 24375 [EILSEQ] Invalid character sequence is detected. | System Interfaces, Issue 6 1251 mbrlen( ) System Interfaces 24376 EXAMPLES 24377 None. 24378 APPLICATION USAGE 24379 None. 24380 RATIONALE 24381 None. 24382 FUTURE DIRECTIONS 24383 None. 24384 SEE ALSO 24385 mbsinit( ), mbrtowc( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 24386 CHANGE HISTORY 24387 First released in Issue 5. Included for alignment with ISO/IEC 9899: 1990/Amendment 1: 1995 24388 (E). | 24389 Issue 6 | 24390 The mbrlen( ) prototype is updated for alignment with the ISO/IEC 9899: 1999 standard. | 1252 Technical Standard (2000) (Draft July 31, 2000) System Interfaces mbrtowc( ) 24391 NAME 24392 mbrtowc - convert a character to a wide-character code (restartable) 24393 SYNOPSIS 24394 #include 24395 size_t mbrtowc(wchar_t *restrict pwc, const char *restrict s, | 24396 size_t n, mbstate_t *restrict ps); | 24397 DESCRIPTION | 24398 CX The functionality described on this reference page is aligned with the ISO C standard. Any 24399 conflict between the requirements described here and the ISO C standard is unintentional. This 24400 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 24401 If s is a null pointer, the mbrtowc( ) function shall be equivalent to the call: 24402 mbrtowc(NULL, "", 1, ps) 24403 In this case, the values of the arguments pwc and n are ignored. 24404 If s is not a null pointer, the mbrtowc( ) function inspects at most n bytes beginning at the byte 24405 pointed to by s to determine the number of bytes needed to complete the next character 24406 (including any shift sequences). If the function determines that the next character is completed, it 24407 determines the value of the corresponding wide character and then, if pwc is not a null pointer, 24408 stores that value in the object pointed to by pwc. If the corresponding wide character is the null 24409 wide character, the resulting state described is the initial conversion state. 24410 If ps is a null pointer, the mbrtowc( ) function uses its own internal mbstate_t object, which is 24411 initialized at program start-up to the initial conversion state. Otherwise, the mbstate_t object 24412 pointed to by ps is used to completely describe the current conversion state of the associated 24413 character sequence. The implementation shall behave as if no function defined in this volume of 24414 IEEE Std. 1003.1-200x calls mbrtowc( ). 24415 XSI The behavior of this function is affected by the LC_CTYPE category of the current locale. 24416 RETURN VALUE 24417 The mbrtowc( ) function shall return the first of the following that applies: 24418 0 If the next n or fewer bytes complete the character that corresponds to the null 24419 wide character (which is the value stored). 24420 positive If the next n or fewer bytes complete a valid character (which is the value 24421 stored); the value returned shall be the number of bytes that complete the 24422 character. 24423 (size_t)-2 If the next n bytes contribute to an incomplete but potentially valid character, 24424 and all n bytes have been processed (no value is stored). When n has at least 24425 the value of the {MB_CUR_MAX} macro, this case can only occur if s points at 24426 a sequence of redundant shift sequences (for implementations with state- 24427 dependent encodings). 24428 (size_t)-1 If an encoding error occurs, in which case the next n or fewer bytes do not 24429 contribute to a complete and valid character (no value is stored). In this case, 24430 [EILSEQ] shall be stored in errno and the conversion state is undefined. | 24431 ERRORS 24432 The mbrtowc( ) function may fail if: 24433 CX [EINVAL] ps points to an object that contains an invalid conversion state. | System Interfaces, Issue 6 1253 mbrtowc( ) System Interfaces 24434 [EILSEQ] Invalid character sequence is detected. | 24435 EXAMPLES 24436 None. 24437 APPLICATION USAGE 24438 None. 24439 RATIONALE 24440 None. 24441 FUTURE DIRECTIONS 24442 None. 24443 SEE ALSO 24444 mbsinit( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 24445 CHANGE HISTORY 24446 First released in Issue 5. Included for alignment with ISO/IEC 9899: 1990/Amendment 1: 1995 24447 (E). | 24448 Issue 6 | 24449 The mbrtowc( ) prototype is updated for alignment with the ISO/IEC 9899: 1999 standard. | 1254 Technical Standard (2000) (Draft July 31, 2000) System Interfaces mbsinit( ) 24450 NAME 24451 mbsinit - determine conversion object status 24452 SYNOPSIS 24453 #include 24454 int mbsinit(const mbstate_t *ps); 24455 DESCRIPTION 24456 CX The functionality described on this reference page is aligned with the ISO C standard. Any 24457 conflict between the requirements described here and the ISO C standard is unintentional. This 24458 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 24459 If ps is not a null pointer, the mbsinit( ) function shall determine whether the object pointed to by 24460 ps describes an initial conversion state. 24461 RETURN VALUE 24462 The mbsinit( ) function shall return non-zero if ps is a null pointer, or if the pointed-to object 24463 describes an initial conversion state; otherwise, it shall return zero. 24464 If an mbstate_t object is altered by any of the functions described as ``restartable'', and is then 24465 used with a different character sequence, or in the other conversion direction, or with a different 24466 LC_CTYPE category setting than on earlier function calls, the behavior is undefined. 24467 ERRORS 24468 No errors are defined. 24469 EXAMPLES 24470 None. 24471 APPLICATION USAGE 24472 The mbstate_t object is used to describe the current conversion state from a particular character 24473 sequence to a wide-character sequence (or vice versa) under the rules of a particular setting of the 24474 LC_CTYPE category of the current locale. 24475 The initial conversion state corresponds, for a conversion in either direction, to the beginning of 24476 a new character sequence in the initial shift state. A zero valued mbstate_t object is at least one 24477 way to describe an initial conversion state. A zero valued mbstate_t object can be used to initiate 24478 conversion involving any character sequence, in any LC_CTYPE category setting. 24479 RATIONALE 24480 None. 24481 FUTURE DIRECTIONS 24482 None. 24483 SEE ALSO 24484 mbrlen( ), mbrtowc( ), wcrtomb( ), mbsrtowcs( ), wcsrtombs( ), the Base Definitions volume of | 24485 IEEE Std. 1003.1-200x, | 24486 CHANGE HISTORY 24487 First released in Issue 5. Included for alignment with ISO/IEC 9899: 1990/Amendment 1: 1995 24488 (E). System Interfaces, Issue 6 1255 mbsrtowcs( ) System Interfaces 24489 NAME 24490 mbsrtowcs - convert a character string to a wide-character string (restartable) 24491 SYNOPSIS 24492 #include 24493 size_t mbsrtowcs(wchar_t *restrict dst, const char **restrict src, | 24494 size_t len, mbstate_t *restrict ps); | 24495 DESCRIPTION | 24496 CX The functionality described on this reference page is aligned with the ISO C standard. Any 24497 conflict between the requirements described here and the ISO C standard is unintentional. This 24498 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 24499 The mbsrtowcs( ) function shall convert a sequence of characters, beginning in the conversion 24500 state described by the object pointed to by ps, from the array indirectly pointed to by src into a 24501 sequence of corresponding wide characters. If dst is not a null pointer, the converted characters 24502 are stored into the array pointed to by dst. Conversion continues up to and including a 24503 terminating null character, which is also stored. Conversion stops early in either of the following 24504 cases: 24505 * A sequence of bytes is encountered that does not form a valid character. 24506 * len codes have been stored into the array pointed to by dst (and dst is not a null pointer). 24507 Each conversion takes place as if by a call to the mbrtowc( ) function. 24508 If dst is not a null pointer, the pointer object pointed to by src is assigned either a null pointer (if 24509 conversion stopped due to reaching a terminating null character) or the address just past the last 24510 character converted (if any). If conversion stopped due to reaching a terminating null character, 24511 and if dst is not a null pointer, the resulting state described is the initial conversion state. 24512 If ps is a null pointer, the mbsrtowcs( ) function uses its own internal mbstate_t object, which is 24513 initialized at program start-up to the initial conversion state. Otherwise, the mbstate_t object 24514 pointed to by ps is used to completely describe the current conversion state of the associated 24515 character sequence. The implementation behaves as if no function defined in this volume of 24516 IEEE Std. 1003.1-200x calls mbsrtowcs( ). 24517 XSI The behavior of this function shall be affected by the LC_CTYPE category of the current locale. 24518 RETURN VALUE 24519 If the input conversion encounters a sequence of bytes that do not form a valid character, an 24520 encoding error occurs. In this case, the mbsrtowcs( ) function stores the value of the macro 24521 [EILSEQ] in errno and shall return (size_t)-1; the conversion state is undefined. Otherwise, it | 24522 shall return the number of characters successfully converted, not including the terminating null 24523 (if any). 24524 ERRORS 24525 The mbsrtowcs( ) function may fail if: 24526 [EINVAL] ps points to an object that contains an invalid conversion state. | 24527 [EILSEQ] Invalid character sequence is detected. | 1256 Technical Standard (2000) (Draft July 31, 2000) System Interfaces mbsrtowcs( ) 24528 EXAMPLES 24529 None. 24530 APPLICATION USAGE 24531 None. 24532 RATIONALE 24533 None. 24534 FUTURE DIRECTIONS 24535 None. 24536 SEE ALSO 24537 mbsinit( ), mbrtowc( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 24538 CHANGE HISTORY 24539 First released in Issue 5. Included for alignment with ISO/IEC 9899: 1990/Amendment 1: 1995 24540 (E). | 24541 Issue 6 | 24542 The mbsrtowcs( ) prototype is updated for alignment with the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 1257 mbstowcs( ) System Interfaces 24543 NAME 24544 mbstowcs - convert a character string to a wide-character string 24545 SYNOPSIS 24546 #include 24547 size_t mbstowcs(wchar_t *restrict pwcs, const char *restrict s, | 24548 size_t n); | 24549 DESCRIPTION | 24550 CX The functionality described on this reference page is aligned with the ISO C standard. Any 24551 conflict between the requirements described here and the ISO C standard is unintentional. This 24552 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 24553 The mbstowcs( ) function shall convert a sequence of characters that begins in the initial shift 24554 state from the array pointed to by s into a sequence of corresponding wide-character codes and 24555 stores not more than n wide-character codes into the array pointed to by pwcs. No characters 24556 that follow a null byte (which is converted into a wide-character code with value 0) shall be 24557 examined or converted. Each character is converted as if by a call to mbtowc( ), except that the 24558 shift state of mbtowc( ) is not affected. 24559 No more than n elements shall be modified in the array pointed to by pwcs. If copying takes 24560 place between objects that overlap, the behavior is undefined. 24561 XSI The behavior of this function shall be affected by the LC_CTYPE category of the current locale. If 24562 pwcs is a null pointer, mbstowcs( ) shall return the length required to convert the entire array 24563 regardless of the value of n, but no values are stored. 24564 RETURN VALUE 24565 CX If an invalid character is encountered, mbstowcs( ) shall return (size_t)-1 and may set errno to 24566 indicate the error. Otherwise, mbstowcs( ) shall return the number of the array elements modified 24567 (or required if pwcs is null), not including a terminating 0 code, if any. The array shall not be 24568 zero-terminated if the value returned is n. 24569 ERRORS 24570 The mbstowcs( ) function may fail if: 24571 XSI [EILSEQ] Invalid byte sequence is detected. | 24572 EXAMPLES 24573 None. 24574 APPLICATION USAGE 24575 None. 24576 RATIONALE 24577 None. 24578 FUTURE DIRECTIONS 24579 None. 24580 SEE ALSO 24581 mblen( ), mbtowc( ), wctomb( ), wcstombs( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 24582 24583 CHANGE HISTORY 24584 First released in Issue 4. Aligned with the ISO C standard. | 1258 Technical Standard (2000) (Draft July 31, 2000) System Interfaces mbstowcs( ) 24585 Issue 6 | 24586 The mbstowcs( ) prototype is updated for alignment with the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 1259 mbtowc( ) System Interfaces 24587 NAME 24588 mbtowc - convert a character to a wide-character code 24589 SYNOPSIS 24590 #include 24591 int mbtowc(wchar_t *restrict pwc, const char *restrict s, size_t n); | 24592 DESCRIPTION | 24593 CX The functionality described on this reference page is aligned with the ISO C standard. Any 24594 conflict between the requirements described here and the ISO C standard is unintentional. This 24595 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 24596 If s is not a null pointer, mbtowc( ) shall determine the number of the bytes that constitute the 24597 character pointed to by s. It then determines the wide-character code for the value of type 24598 wchar_t that corresponds to that character. (The value of the wide-character code corresponding 24599 to the null byte is 0.) If the character is valid and pwc is not a null pointer, mbtowc( ) stores the 24600 wide-character code in the object pointed to by pwc. 24601 The behavior of this function is affected by the LC_CTYPE category of the current locale. For a 24602 state-dependent encoding, this function is placed into its initial state by a call for which its 24603 character pointer argument, s, is a null pointer. Subsequent calls with s as other than a null 24604 pointer cause the internal state of the function to be altered as necessary. A call with s as a null 24605 pointer causes this function to return a non-zero value if encodings have state dependency, and 24606 0 otherwise. If the implementation employs special bytes to change the shift state, these bytes do 24607 not produce separate wide-character codes, but are grouped with an adjacent character. 24608 Changing the LC_CTYPE category causes the shift state of this function to be indeterminate. At 24609 most n bytes of the array pointed to by s shall be examined. 24610 The implementation shall behave as if no function defined in this volume of 24611 IEEE Std. 1003.1-200x calls mbtowc( ). 24612 RETURN VALUE 24613 If s is a null pointer, mbtowc( ) shall return a non-zero or 0 value, if character encodings, 24614 respectively, do or do not have state-dependent encodings. If s is not a null pointer, mbtowc( ) 24615 shall either return 0 (if s points to the null byte), or return the number of bytes that constitute the 24616 CX converted character (if the next n or fewer bytes form a valid character), or return -1 and may 24617 set errno to indicate the error(if they do not form a valid character). 24618 In no case shall the value returned be greater than n or the value of the {MB_CUR_MAX} macro. 24619 ERRORS 24620 The mbtowc( ) function may fail if: 24621 XSI [EILSEQ] Invalid character sequence is detected. | 24622 EXAMPLES 24623 None. 24624 APPLICATION USAGE 24625 None. 24626 RATIONALE 24627 None. 24628 FUTURE DIRECTIONS 24629 None. 1260 Technical Standard (2000) (Draft July 31, 2000) System Interfaces mbtowc( ) 24630 SEE ALSO 24631 mblen( ), mbstowcs( ), wctomb( ), wcstombs( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 24632 24633 CHANGE HISTORY 24634 First released in Issue 4. Aligned with the ISO C standard. | 24635 Issue 6 | 24636 The mbtowc( ) prototype is updated for alignment with the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 1261 memccpy( ) System Interfaces 24637 NAME 24638 memccpy - copy bytes in memory 24639 SYNOPSIS 24640 XSI #include 24641 void *memccpy(void *restrict s1, const void *restrict s2, | 24642 int c, size_t n); | 24643 | 24644 DESCRIPTION 24645 The memccpy( ) function shall copy bytes from memory area s2 into s1, stopping after the first 24646 occurrence of byte c (converted to an unsigned char) is copied, or after n bytes are copied, 24647 whichever comes first. If copying takes place between objects that overlap, the behavior is 24648 undefined. 24649 RETURN VALUE 24650 The memccpy( ) function shall return a pointer to the byte after the copy of c in s1, or a null 24651 pointer if c was not found in the first n bytes of s2. 24652 ERRORS 24653 No errors are defined. 24654 EXAMPLES 24655 None. 24656 APPLICATION USAGE 24657 The memccpy( ) function does not check for the overflow of the receiving memory area. 24658 RATIONALE 24659 None. 24660 FUTURE DIRECTIONS 24661 None. 24662 SEE ALSO 24663 The Base Definitions volume of IEEE Std. 1003.1-200x, | 24664 CHANGE HISTORY 24665 First released in Issue 1. Derived from Issue 1 of the SVID. | 24666 Issue 4 24667 The type of argument s2 is changed from void* to const void*. 24668 Reference to use of the header is removed from the APPLICATION USAGE 24669 section. 24670 The FUTURE DIRECTIONS section is removed. | 24671 Issue 6 | 24672 The restrict keyword is added to the memccpy( ) prototype for alignment with the | 24673 ISO/IEC 9899: 1999 standard. | 1262 Technical Standard (2000) (Draft July 31, 2000) System Interfaces memchr( ) 24674 NAME 24675 memchr - find byte in memory 24676 SYNOPSIS 24677 #include 24678 void *memchr(const void *s, int c, size_t n); 24679 DESCRIPTION 24680 CX The functionality described on this reference page is aligned with the ISO C standard. Any 24681 conflict between the requirements described here and the ISO C standard is unintentional. This 24682 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 24683 The memchr( ) function shall locate the first occurrence of c (converted to an unsigned char) in 24684 the initial n bytes (each interpreted as unsigned char) of the object pointed to by s. 24685 RETURN VALUE 24686 The memchr( ) function shall return a pointer to the located byte, or a null pointer if the byte does 24687 not occur in the object. 24688 ERRORS 24689 No errors are defined. 24690 EXAMPLES 24691 None. 24692 APPLICATION USAGE 24693 None. 24694 RATIONALE 24695 None. 24696 FUTURE DIRECTIONS 24697 None. 24698 SEE ALSO 24699 The Base Definitions volume of IEEE Std. 1003.1-200x, | 24700 CHANGE HISTORY 24701 First released in Issue 1. Derived from Issue 1 of the SVID. | 24702 Issue 4 24703 The APPLICATION USAGE section is removed. 24704 The following changes are incorporated for alignment with the ISO C standard: 24705 * The function is no longer marked as an extension. 24706 * The type of argument s is changed from void* to const void*. System Interfaces, Issue 6 1263 memcmp( ) System Interfaces 24707 NAME 24708 memcmp - compare bytes in memory 24709 SYNOPSIS 24710 #include 24711 int memcmp(const void *s1, const void *s2, size_t n); 24712 DESCRIPTION 24713 CX The functionality described on this reference page is aligned with the ISO C standard. Any 24714 conflict between the requirements described here and the ISO C standard is unintentional. This 24715 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 24716 The memcmp( ) function shall compare the first n bytes (each interpreted as unsigned char) of the 24717 object pointed to by s1 to the first n bytes of the object pointed to by s2. 24718 The sign of a non-zero return value shall be determined by the sign of the difference between the 24719 values of the first pair of bytes (both interpreted as type unsigned char) that differ in the objects 24720 being compared. 24721 RETURN VALUE 24722 The memcmp( ) function shall return an integer greater than, equal to, or less than 0, if the object 24723 pointed to by s1 is greater than, equal to, or less than the object pointed to by s2, respectively. 24724 ERRORS 24725 No errors are defined. 24726 EXAMPLES 24727 None. 24728 APPLICATION USAGE 24729 None. 24730 RATIONALE 24731 None. 24732 FUTURE DIRECTIONS 24733 None. 24734 SEE ALSO 24735 The Base Definitions volume of IEEE Std. 1003.1-200x, | 24736 CHANGE HISTORY 24737 First released in Issue 1. Derived from Issue 1 of the SVID. | 24738 Issue 4 24739 The RETURN VALUE section is clarified. 24740 The APPLICATION USAGE section is removed. 24741 The following changes are incorporated for alignment with the ISO C standard: 24742 * The function is no longer marked as an extension. 24743 * The type of arguments s1 and s2 are changed from void* to const void*. 1264 Technical Standard (2000) (Draft July 31, 2000) System Interfaces memcpy( ) 24744 NAME 24745 memcpy - copy bytes in memory 24746 SYNOPSIS 24747 #include 24748 void *memcpy(void *restrict s1, const void *restrict s2, size_t n); | 24749 DESCRIPTION | 24750 CX The functionality described on this reference page is aligned with the ISO C standard. Any 24751 conflict between the requirements described here and the ISO C standard is unintentional. This 24752 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 24753 The memcpy( ) function shall copy n bytes from the object pointed to by s2 into the object pointed 24754 to by s1. If copying takes place between objects that overlap, the behavior is undefined. 24755 RETURN VALUE 24756 The memcpy( ) function shall return s1; no return value is reserved to indicate an error. 24757 ERRORS 24758 No errors are defined. 24759 EXAMPLES 24760 None. 24761 APPLICATION USAGE 24762 The memcpy( ) function does not check for the overflowing of the receiving memory area. 24763 RATIONALE 24764 None. 24765 FUTURE DIRECTIONS 24766 None. 24767 SEE ALSO 24768 The Base Definitions volume of IEEE Std. 1003.1-200x, | 24769 CHANGE HISTORY 24770 First released in Issue 1. Derived from Issue 1 of the SVID. | 24771 Issue 4 24772 Reference to use of the header is removed from the APPLICATION USAGE 24773 section, and a note about overflow checking has been added. 24774 The FUTURE DIRECTIONS section is removed. 24775 The following changes are incorporated for alignment with the ISO C standard: 24776 * The function is no longer marked as an extension. 24777 * The type of argument s2 is changed from void* to const void*. 24778 Issue 6 | 24779 The memcpy( ) prototype is updated for alignment with the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 1265 memmove( ) System Interfaces 24780 NAME 24781 memmove - copy bytes in memory with overlapping areas 24782 SYNOPSIS 24783 #include 24784 void *memmove(void *s1, const void *s2, size_t n); 24785 DESCRIPTION 24786 CX The functionality described on this reference page is aligned with the ISO C standard. Any 24787 conflict between the requirements described here and the ISO C standard is unintentional. This 24788 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 24789 The memmove( ) function shall copy n bytes from the object pointed to by s2 into the object 24790 pointed to by s1. Copying takes place as if the n bytes from the object pointed to by s2 are first 24791 copied into a temporary array of n bytes that does not overlap the objects pointed to by s1 and 24792 s2, and then the n bytes from the temporary array are copied into the object pointed to by s1. 24793 RETURN VALUE 24794 The memmove( ) function shall return s1; no return value is reserved to indicate an error. 24795 ERRORS 24796 No errors are defined. 24797 EXAMPLES 24798 None. 24799 APPLICATION USAGE 24800 None. 24801 RATIONALE 24802 None. 24803 FUTURE DIRECTIONS 24804 None. 24805 SEE ALSO 24806 The Base Definitions volume of IEEE Std. 1003.1-200x, | 24807 CHANGE HISTORY 24808 First released in Issue 4. Derived from the ANSI C standard. | 1266 Technical Standard (2000) (Draft July 31, 2000) System Interfaces memset( ) 24809 NAME 24810 memset - set bytes in memory 24811 SYNOPSIS 24812 #include 24813 void *memset(void *s, int c, size_t n); 24814 DESCRIPTION 24815 CX The functionality described on this reference page is aligned with the ISO C standard. Any 24816 conflict between the requirements described here and the ISO C standard is unintentional. This 24817 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 24818 The memset( ) function shall copy c (converted to an unsigned char) into each of the first n bytes 24819 of the object pointed to by s. 24820 RETURN VALUE 24821 The memset( ) function shall return s; no return value is reserved to indicate an error. 24822 ERRORS 24823 No errors are defined. 24824 EXAMPLES 24825 None. 24826 APPLICATION USAGE 24827 None. 24828 RATIONALE 24829 None. 24830 FUTURE DIRECTIONS 24831 None. 24832 SEE ALSO 24833 The Base Definitions volume of IEEE Std. 1003.1-200x, | 24834 CHANGE HISTORY 24835 First released in Issue 1. Derived from Issue 1 of the SVID. | 24836 Issue 4 24837 The APPLICATION USAGE section is removed. 24838 The following change is incorporated for alignment with the ISO C standard: 24839 * The function is no longer marked as an extension. System Interfaces, Issue 6 1267 mkdir( ) System Interfaces 24840 NAME 24841 mkdir - make a directory 24842 SYNOPSIS 24843 #include 24844 int mkdir(const char *path, mode_t mode); 24845 DESCRIPTION 24846 The mkdir( ) function creates a new directory with name path. The file permission bits of the new 24847 directory are initialized from mode. These file permission bits of the mode argument are modified 24848 by the process' file creation mask. 24849 When bits in mode other than the file permission bits are set, the meaning of these additional bits | 24850 is implementation-defined. | 24851 The directory's user ID is set to the process' effective user ID. The directory's group ID shall be 24852 set to the group ID of the parent directory or to the effective group ID of the process. 24853 The newly created directory shall be an empty directory. 24854 If path names a symbolic link, mkdir( ) shall fail and set errno to [EEXIST]. 24855 Upon successful completion, mkdir( ) shall mark for update the st_atime, st_ctime, and st_mtime 24856 fields of the directory. Also, the st_ctime and st_mtime fields of the directory that contains the 24857 new entry shall be marked for update. 24858 RETURN VALUE 24859 Upon successful completion, mkdir( ) shall return 0. Otherwise, -1 shall be returned, no directory 24860 shall be created, and errno shall be set to indicate the error. 24861 ERRORS 24862 The mkdir( ) function shall fail if: 24863 [EACCES] Search permission is denied on a component of the path prefix, or write | 24864 permission is denied on the parent directory of the directory to be created. 24865 [EEXIST] The named file exists. | 24866 [ELOOP] A loop exists in symbolic links encountered during resolution of the path | 24867 argument. | 24868 [EMLINK] The link count of the parent directory would exceed {LINK_MAX}. | 24869 [ENAMETOOLONG] | 24870 The length of the path argument exceeds {PATH_MAX} or a path name 24871 component is longer than {NAME_MAX}. | 24872 [ENOENT] A component of the path prefix specified by path does not name an existing | 24873 directory or path is an empty string. 24874 [ENOSPC] The file system does not contain enough space to hold the contents of the new | 24875 directory or to extend the parent directory of the new directory. 24876 [ENOTDIR] A component of the path prefix is not a directory. | 24877 [EROFS] The parent directory resides on a read-only file system. | 24878 The mkdir( ) function may fail if: 24879 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 24880 resolution of the path argument. | 1268 Technical Standard (2000) (Draft July 31, 2000) System Interfaces mkdir( ) 24881 [ENAMETOOLONG] | 24882 As a result of encountering a symbolic link in resolution of the path argument, 24883 the length of the substituted path name string exceeded {PATH_MAX}. | 24884 EXAMPLES 24885 Creating a Directory 24886 The following example shows how to create a directory named /home/cnd/mod1, with 24887 read/write/search permissions for owner and group, and with read/search permissions for 24888 others. 24889 #include 24890 #include 24891 int status; 24892 ... 24893 status = mkdir("/home/cnd/mod1", S_IRWXU | S_IRWXG | S_IROTH | S_IXOTH); 24894 APPLICATION USAGE 24895 None. 24896 RATIONALE 24897 The mkdir( ) function originated in 4.2 BSD and was added to System V in Release 3.0. 24898 4.3 BSD detects [ENAMETOOLONG]. | 24899 See getgroups( ) about the group of a newly created directory. 24900 FUTURE DIRECTIONS 24901 None. 24902 SEE ALSO 24903 umask( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , | 24904 CHANGE HISTORY 24905 First released in Issue 3. 24906 Entry included for alignment with the POSIX.1-1988 standard. 24907 Issue 4 24908 The header is now marked as optional (OH); this header need not be included on 24909 XSI-conformant systems. 24910 The following change is incorporated for alignment with the ISO POSIX-1 standard: 24911 * The type of argument path is changed from char* to const char*. 24912 The following changes are incorporated for alignment with the FIPS requirements: 24913 * In the ERRORS section, the condition whereby [ENAMETOOLONG] is returned if a path 24914 name component is larger than {NAME_MAX} is now defined as mandatory and marked as 24915 an extension. 24916 Issue 4, Version 2 24917 The ERRORS section is updated for X/OPEN UNIX conformance as follows: 24918 * It states that [ELOOP] is returned if too many symbolic links are encountered during path 24919 name resolution. 24920 * A second [ENAMETOOLONG] condition is defined that may report excessive length of an 24921 intermediate result of path name resolution of a symbolic link. System Interfaces, Issue 6 1269 mkdir( ) System Interfaces 24922 Issue 6 24923 In the SYNOPSIS, the inclusion of is no longer required. 24924 The following changes are made for alignment with the ISO POSIX-1: 1996 standard: 24925 * The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. 24926 This is since behavior may vary from one file system to another. 24927 The following new requirements on POSIX implementations derive from alignment with the 24928 Single UNIX Specification: 24929 * The requirement to include has been removed. Although was 24930 required for conforming implementations of previous POSIX specifications, it was not 24931 required for UNIX applications. 24932 * The [ELOOP] mandatory error condition is added. 24933 * A second [ENAMETOOLONG] is added as an optional error condition. 24934 The following changes were made to align with the IEEE P1003.1a draft standard: 24935 * The [ELOOP] optional error condition is added. 1270 Technical Standard (2000) (Draft July 31, 2000) System Interfaces mkfifo( ) 24936 NAME 24937 mkfifo - make a FIFO special file 24938 SYNOPSIS 24939 #include 24940 int mkfifo(const char *path, mode_t mode); 24941 DESCRIPTION 24942 The mkfifo( ) function shall create a new FIFO special file named by the path name pointed to by 24943 path. The file permission bits of the new FIFO are initialized from mode. The file permission bits 24944 of the mode argument are modified by the process' file creation mask. 24945 When bits in mode other than the file permission bits are set, the effect is implementation- | 24946 defined. | 24947 If path names a symbolic link, mkfifo( ) shall fail and set errno to [EEXIST]. | 24948 The FIFO's user ID shall be set to the process' effective user ID. The FIFO's group ID shall be set | 24949 to the group ID of the parent directory or to the effective group ID of the process. | 24950 Upon successful completion, mkfifo( ) shall mark for update the st_atime, st_ctime, and st_mtime 24951 fields of the file. Also, the st_ctime and st_mtime fields of the directory that contains the new 24952 entry shall be marked for update. 24953 RETURN VALUE 24954 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned, no FIFO shall 24955 be created, and errno shall be set to indicate the error. 24956 ERRORS 24957 The mkfifo( ) function shall fail if: 24958 [EACCES] A component of the path prefix denies search permission, or write permission | 24959 is denied on the parent directory of the FIFO to be created. 24960 [EEXIST] The named file already exists. | 24961 [ELOOP] A loop exists in symbolic links encountered during resolution of the path | 24962 argument. | 24963 [ENAMETOOLONG] | 24964 The length of the path argument exceeds {PATH_MAX} or a path name 24965 component is longer than {NAME_MAX}. | 24966 [ENOENT] A component of the path prefix specified by path does not name an existing | 24967 directory or path is an empty string. 24968 [ENOSPC] The directory that would contain the new file cannot be extended or the file | 24969 system is out of file-allocation resources. 24970 [ENOTDIR] A component of the path prefix is not a directory. | 24971 [EROFS] The named file resides on a read-only file system. | 24972 The mkfifo( ) function may fail if: 24973 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 24974 resolution of the path argument. | 24975 [ENAMETOOLONG] | 24976 As a result of encountering a symbolic link in resolution of the path argument, 24977 the length of the substituted path name string exceeded {PATH_MAX}. | System Interfaces, Issue 6 1271 mkfifo( ) System Interfaces 24978 EXAMPLES 24979 Creating a FIFO File 24980 The following example shows how to create a FIFO file named /home/cnd/mod_done, with 24981 read/write permissions for owner, and with read permissions for group and others. 24982 #include 24983 #include 24984 int status; 24985 ... 24986 status = mkfifo("/home/cnd/mod_done", S_IWUSR | S_IRUSR | 24987 S_IRGRP | S_IROTH); 24988 APPLICATION USAGE 24989 None. 24990 RATIONALE 24991 The syntax of this function is intended to maintain compatibility with historical 24992 implementations of mknod( ). The latter function was included in the 1984 /usr/group standard 24993 but only for use in creating FIFO special files. The mknod( ) function was originally excluded 24994 from the POSIX.1-1988 standard as implementation-defined and replaced by mkdir( ) and | 24995 mkfifo( ). The mknod( ) function is now included for alignment with the Single UNIX 24996 Specification. 24997 See getgroups( ) about the group of a newly created FIFO. 24998 FUTURE DIRECTIONS 24999 None. 25000 SEE ALSO 25001 umask( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , | 25002 CHANGE HISTORY 25003 First released in Issue 3. 25004 Entry included for alignment with the POSIX.1-1988 standard. 25005 Issue 4 25006 The header is now marked as optional (OH); this header need not be included on 25007 XSI-conformant systems. 25008 The following changes are incorporated for alignment with the ISO POSIX-1 standard: 25009 * The type of argument path is changed from char* to const char*. 25010 * The description of [EACCES] is updated to indicate that this error is also returned if write 25011 permission is denied to the parent directory. 25012 The following changes are incorporated for alignment with the FIPS requirements: 25013 * In the ERRORS section, the condition whereby [ENAMETOOLONG] is returned if a path 25014 name component is larger that {NAME_MAX} is now defined as mandatory and marked as 25015 an extension. 25016 Issue 4, Version 2 25017 The ERRORS section is updated for X/OPEN UNIX conformance as follows: 25018 * It states that [ELOOP] is returned if too many symbolic links are encountered during path 25019 name resolution. 1272 Technical Standard (2000) (Draft July 31, 2000) System Interfaces mkfifo( ) 25020 * A second [ENAMETOOLONG] condition is defined that may report excessive length of an 25021 intermediate result of path name resolution of a symbolic link. 25022 Issue 6 25023 In the SYNOPSIS, the inclusion of is no longer required. 25024 The following changes are made for alignment with the ISO POSIX-1: 1996 standard: 25025 * The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. 25026 This is since behavior may vary from one file system to another. 25027 The following new requirements on POSIX implementations derive from alignment with the 25028 Single UNIX Specification: 25029 * The requirement to include has been removed. Although was 25030 required for conforming implementations of previous POSIX specifications, it was not 25031 required for UNIX applications. 25032 * The [ELOOP] mandatory error condition is added. 25033 * A second [ENAMETOOLONG] is added as an optional error condition. 25034 The following changes were made to align with the IEEE P1003.1a draft standard: 25035 * The [ELOOP] optional error condition is added. System Interfaces, Issue 6 1273 mknod( ) System Interfaces 25036 NAME 25037 mknod - make a directory, a special or regular file 25038 SYNOPSIS 25039 XSI #include 25040 int mknod(const char *path, mode_t mode, dev_t dev); 25041 25042 DESCRIPTION 25043 The mknod( ) function shall create a new file named by the path name to which the argument 25044 path points. 25045 The file type for path is OR'ed into the mode argument, and the application shall select one of the 25046 following symbolic constants: 25047 __________________________________________ 25048 _ Name Description _________________________________________ 25049 S_IFIFO FIFO-special 25050 S_IFCHR Character-special (non-portable) 25051 S_IFDIR Directory (non-portable) 25052 S_IFBLK Block-special (non-portable) 25053 _ S_IFREG Regular (non-portable) _________________________________________ 25054 The only portable use of mknod( ) is to create a FIFO-special file. If mode is not S_IFIFO or dev is 25055 not 0, the behavior of mknod( ) is unspecified. 25056 The permissions for the new file are OR'ed into the mode argument, and may be selected from 25057 any combination of the following symbolic constants: 25058 ___________________________________________________ 25059 _ Name Description __________________________________________________ 25060 S_ISUID Set user ID on execution. 25061 S_ISGID Set group ID on execution. 25062 S_IRWXU Read, write, or execute (search) by owner. 25063 S_IRUSR Read by owner. 25064 S_IWUSR Write by owner. 25065 S_IXUSR Execute (search) by owner. 25066 S_IRWXG Read, write, or execute (search) by group. 25067 S_IRGRP Read by group. 25068 S_IWGRP Write by group. 25069 S_IXGRP Execute (search) by group. 25070 S_IRWXO Read, write, or execute (search) by others. 25071 S_IROTH Read by others. 25072 S_IWOTH Write by others. 25073 S_IXOTH Execute (search) by others. 25074 _ S_ISVTX On directories, restricted deletion flag. __________________________________________________ 25075 The user ID of the file is initialized to the effective user ID of the process. The group ID of the file 25076 is initialized to either the effective group ID of the process or the group ID of the parent 25077 directory. 25078 The owner, group, and other permission bits of mode are modified by the file mode creation 25079 mask of the process. The mknod( ) function clears each bit whose corresponding bit in the file 25080 mode creation mask of the process is set. 1274 Technical Standard (2000) (Draft July 31, 2000) System Interfaces mknod( ) 25081 If path names a symbolic link, mknod( ) shall fail and set errno to [EEXIST]. | 25082 Upon successful completion, mknod( ) shall mark for update the st_atime, st_ctime, and st_mtime | 25083 fields of the file. Also, the st_ctime and st_mtime fields of the directory that contains the new 25084 entry shall be marked for update. 25085 Only a process with appropriate privileges may invoke mknod( ) for file types other than FIFO- 25086 special. 25087 RETURN VALUE 25088 Upon successful completion, mknod( ) shall return 0. Otherwise, it shall return -1, the new file 25089 shall not be created, and errno shall be set to indicate the error. 25090 ERRORS 25091 The mknod( ) function shall fail if: 25092 [EACCES] A component of the path prefix denies search permission, or write permission | 25093 is denied on the parent directory. | 25094 [EEXIST] The named file exists. | 25095 [EINVAL] An invalid argument exists. | 25096 [EIO] An I/O error occurred while accessing the file system. | 25097 [ELOOP] A loop exists in symbolic links encountered during resolution of the path | 25098 argument. | 25099 [ENAMETOOLONG] | 25100 The length of a path name exceeds {PATH_MAX} or a path name component | 25101 is longer than {NAME_MAX}. | 25102 [ENOENT] A component of the path prefix specified by path does not name an existing | 25103 directory or path is an empty string. | 25104 [ENOSPC] The directory that would contain the new file cannot be extended or the file | 25105 system is out of file allocation resources. | 25106 [ENOTDIR] A component of the path prefix is not a directory. | 25107 [EPERM] The invoking process does not have appropriate privileges and the file type is | 25108 not FIFO-special. | 25109 [EROFS] The directory in which the file is to be created is located on a read-only file | 25110 system. | 25111 The mknod( ) function may fail if: 25112 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during | 25113 resolution of the path argument. | 25114 [ENAMETOOLONG] | 25115 Path name resolution of a symbolic link produced an intermediate result 25116 whose length exceeds {PATH_MAX}. System Interfaces, Issue 6 1275 mknod( ) System Interfaces 25117 EXAMPLES 25118 Creating a FIFO Special File 25119 The following example shows how to create a FIFO special file named /home/cnd/mod_done, 25120 with read/write permissions for owner, and with read permissions for group and others. 25121 #include 25122 #include 25123 dev_t dev; 25124 int status; 25125 ... 25126 status = mknod("/home/cnd/mod_done", S_IFIFO | S_IWUSR | 25127 S_IRUSR | S_IRGRP | S_IROTH, dev); 25128 APPLICATION USAGE 25129 mkfifo( ) is preferred over this function for making FIFO special files. 25130 RATIONALE 25131 None. 25132 FUTURE DIRECTIONS 25133 None. 25134 SEE ALSO 25135 chmod( ), creat( ), exec, mkdir( ), mkfifo( ), open( ), stat( ), umask( ), the Base Definitions volume of | 25136 IEEE Std. 1003.1-200x, | 25137 CHANGE HISTORY 25138 First released in Issue 4, Version 2. 25139 Issue 5 25140 Moved from X/OPEN UNIX extension to BASE. 25141 Issue 6 25142 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. | 25143 The wording of the mandatory [ELOOP] error condition is updated, and a second optional | 25144 [ELOOP] error condition is added. | 1276 Technical Standard (2000) (Draft July 31, 2000) System Interfaces mkstemp( ) 25145 NAME 25146 mkstemp - make a unique file name 25147 SYNOPSIS 25148 XSI #include 25149 int mkstemp(char *template); 25150 25151 DESCRIPTION 25152 The mkstemp( ) function shall replace the contents of the string pointed to by template by a unique 25153 file name, and return a file descriptor for the file open for reading and writing. The function thus 25154 prevents any possible race condition between testing whether the file exists and opening it for 25155 use. The string in template should look like a file name with six trailing Xs; mkstemp( ) replaces 25156 each X with a character from the portable file name character set. The characters are chosen such 25157 that the resulting name does not duplicate the name of an existing file at the time of a call to 25158 mkstemp( ). 25159 RETURN VALUE 25160 Upon successful completion, mkstemp( ) shall return an open file descriptor. Otherwise, -1 shall 25161 be returned if no suitable file could be created. 25162 ERRORS 25163 No errors are defined. 25164 EXAMPLES 25165 Generating a File Name 25166 The following example creates a file with a 10-character name beginning with the characters 25167 "file" and opens the file for reading and writing. The value returned as the value of fd is a file 25168 descriptor that identifies the file. 25169 #include 25170 ... 25171 char *template = "/tmp/fileXXXXXX"; 25172 int fd; 25173 fd = mkstemp(template); 25174 APPLICATION USAGE 25175 It is possible to run out of letters. 25176 The mkstemp( ) function need not check to determine whether the file name part of template 25177 exceeds the maximum allowable file name length. 25178 RATIONALE 25179 None. 25180 FUTURE DIRECTIONS 25181 None. 25182 SEE ALSO 25183 getpid( ), open( ), tmpfile( ), tmpnam( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 25184 System Interfaces, Issue 6 1277 mkstemp( ) System Interfaces 25185 CHANGE HISTORY 25186 First released in Issue 4, Version 2. 25187 Issue 5 25188 Moved from X/OPEN UNIX extension to BASE. 1278 Technical Standard (2000) (Draft July 31, 2000) System Interfaces mktemp( ) 25189 NAME 25190 mktemp - make a unique file name (LEGACY) 25191 SYNOPSIS 25192 XSI #include 25193 char *mktemp(char *template); 25194 25195 DESCRIPTION 25196 The mktemp( ) function shall replace the contents of the string pointed to by template by a unique 25197 file name and return template. The application shall initialize template to be a file name with six 25198 trailing Xs; mktemp( ) shall replace each X with a single byte character from the portable file 25199 name character set. 25200 RETURN VALUE 25201 The mktemp( ) function shall return the pointer template. If a unique name cannot be created, 25202 template shall point to a null string. 25203 ERRORS 25204 No errors are defined. 25205 EXAMPLES 25206 Generating a File Name 25207 The following example replaces the contents of the "template" string with a 10-character file 25208 name beginning with the characters "file" and returns a pointer to the "template" string 25209 that contains the new file name. 25210 #include 25211 ... 25212 char *template = "/tmp/fileXXXXXX"; 25213 char *ptr; 25214 ptr = mktemp(template); 25215 APPLICATION USAGE 25216 Between the time a path name is created and the file opened, it is possible for some other process 25217 to create a file with the same name. The mkstemp( ) function avoids this problem and is preferred 25218 over this function. 25219 RATIONALE 25220 None. 25221 FUTURE DIRECTIONS 25222 This function may be withdrawn in a future version. 25223 SEE ALSO 25224 mkstemp( ), tmpfile( ), tmpnam( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 25225 CHANGE HISTORY 25226 First released in Issue 4, Version 2. 25227 Issue 5 25228 Moved from X/OPEN UNIX extension to BASE. System Interfaces, Issue 6 1279 mktemp( ) System Interfaces 25229 Issue 6 25230 This function is marked LEGACY. 25231 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 1280 Technical Standard (2000) (Draft July 31, 2000) System Interfaces mktime( ) 25232 NAME 25233 mktime - convert broken-down time into time since the Epoch 25234 SYNOPSIS 25235 #include 25236 time_t mktime(struct tm *timeptr); 25237 DESCRIPTION 25238 CX The functionality described on this reference page is aligned with the ISO C standard. Any 25239 conflict between the requirements described here and the ISO C standard is unintentional. This 25240 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 25241 The mktime( ) function shall convert the broken-down time, expressed as local time, in the 25242 structure pointed to by timeptr, into a time since the Epoch value with the same encoding as that 25243 of the values returned by time( ). The original values of the tm_wday and tm_yday components of 25244 the structure are ignored, and the original values of the other components are not restricted to 25245 the ranges described in . 25246 CX A positive or 0 value for tm_isdst shall cause mktime( ) to presume initially that Daylight Savings 25247 Time, respectively, is or is not in effect for the specified time. A negative value for tm_isdst shall 25248 cause mktime( ) to attempt to determine whether Daylight Saving Time is in effect for the 25249 specified time. 25250 Local timezone information shall be set as though mktime( ) called tzset( ). 25251 Upon successful completion, the values of the tm_wday and tm_yday components of the structure 25252 shall be set appropriately, and the other components are set to represent the specified time since 25253 the Epoch, but with their values forced to the ranges indicated in the entry; the final 25254 value of tm_mday shall not be set until tm_mon and tm_year are determined. 25255 RETURN VALUE 25256 The mktime( ) function shall return the specified time since the Epoch encoded as a value of type 25257 time_t. If the time since the Epoch cannot be represented, the function shall return the value 25258 (time_t)-1. 25259 ERRORS 25260 No errors are defined. 25261 EXAMPLES 25262 What day of the week is July 4, 2001? 25263 #include 25264 #include 25265 struct tm time_str; 25266 char daybuf[20]; 25267 int main(void) 25268 { 25269 time_str.tm_year = 2001 - 1900; 25270 time_str.tm_mon = 7 - 1; 25271 time_str.tm_mday = 4; 25272 time_str.tm_hour = 0; 25273 time_str.tm_min = 0; 25274 time_str.tm_sec = 1; 25275 time_str.tm_isdst = -1; 25276 if (mktime(&time_str) == -1) System Interfaces, Issue 6 1281 mktime( ) System Interfaces 25277 (void)puts("-unknown-"); 25278 else { 25279 (void)strftime(daybuf, sizeof(daybuf), "%A", &time_str); 25280 (void)puts(daybuf); 25281 } 25282 return 0; 25283 } 25284 APPLICATION USAGE 25285 None. 25286 RATIONALE 25287 None. 25288 FUTURE DIRECTIONS 25289 None. 25290 SEE ALSO 25291 asctime( ), clock( ), ctime( ), difftime( ), gmtime( ), localtime( ), strftime( ), strptime( ), time( ), utime( ), | 25292 the Base Definitions volume of IEEE Std. 1003.1-200x, | 25293 CHANGE HISTORY 25294 First released in Issue 3. 25295 Entry included for alignment with the POSIX.1-1988 standard and the ANSI C standard. 25296 Issue 4 25297 In the DESCRIPTION, a paragraph is added indicating the possible settings of tm_isdst, and 25298 reference to setting of tm_sec for leap seconds or double leap seconds is removed (although this 25299 functionality is still supported). 25300 In the EXAMPLES section, the sample code is updated to use ISO C standard syntax. 25301 Issue 6 25302 Extensions beyond the ISO C standard are now marked. 1282 Technical Standard (2000) (Draft July 31, 2000) System Interfaces mlock( ) 25303 NAME 25304 mlock, munlock - lock or unlock a range of process address space (REALTIME) 25305 SYNOPSIS 25306 MLR #include 25307 int mlock(const void * addr, size_t len); 25308 int munlock(const void * addr, size_t len); 25309 25310 DESCRIPTION 25311 The mlock( ) function shall cause those whole pages containing any part of the address space of 25312 the process starting at address addr and continuing for len bytes to be memory-resident until 25313 unlocked or until the process exits or execs another process image. The implementation may 25314 require that addr be a multiple of {PAGESIZE}. 25315 The munlock( ) function shall unlock those whole pages containing any part of the address space 25316 of the process starting at address addr and continuing for len bytes, regardless of how many 25317 times mlock( ) has been called by the process for any of the pages in the specified range. The 25318 implementation may require that addr be a multiple of the {PAGESIZE}. 25319 If any of the pages in the range specified to a call to munlock( ) are also mapped into the address 25320 spaces of other processes, any locks established on those pages by another process are 25321 unaffected by the call of this process to munlock( ). If any of the pages in the range specified by a 25322 call to munlock( ) are also mapped into other portions of the address space of the calling process 25323 outside the range specified, any locks established on those pages via the other mappings are also 25324 unaffected by this call. 25325 Upon successful return from mlock( ), pages in the specified range shall be locked and memory- 25326 resident. Upon successful return from munlock( ), pages in the specified range shall be unlocked 25327 with respect to the address space of the process. Memory residency of unlocked pages is 25328 unspecified. 25329 The appropriate privilege is required to lock process memory with mlock( ). 25330 RETURN VALUE 25331 Upon successful completion, the mlock( ) and munlock( ) functions shall return a value of zero. 25332 Otherwise, no change is made to any locks in the address space of the process, and the function 25333 shall return a value of -1 and set errno to indicate the error. 25334 ERRORS 25335 The mlock( ) and munlock( ) functions shall fail if: 25336 [ENOMEM] Some or all of the address range specified by the addr and len arguments does | 25337 not correspond to valid mapped pages in the address space of the process. 25338 The mlock( ) function shall fail if: 25339 [EAGAIN] Some or all of the memory identified by the operation could not be locked | 25340 when the call was made. 25341 The mlock( ) and munlock( ) functions may fail if: 25342 [EINVAL] The addr argument is not a multiple of {PAGESIZE}. | 25343 The mlock( ) function may fail if: 25344 [ENOMEM] Locking the pages mapped by the specified range would exceed an | 25345 implementation-defined limit on the amount of memory that the process may | 25346 lock. System Interfaces, Issue 6 1283 mlock( ) System Interfaces 25347 [EPERM] The calling process does not have the appropriate privilege to perform the | 25348 requested operation. 25349 EXAMPLES 25350 None. 25351 APPLICATION USAGE 25352 None. 25353 RATIONALE 25354 None. 25355 FUTURE DIRECTIONS 25356 None. 25357 SEE ALSO 25358 exec, exit( ), fork( ), mlockall( ), munmap( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 25359 25360 CHANGE HISTORY 25361 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 25362 Issue 6 25363 The mlock( ) and munlock( ) functions are marked as part of the Range Memory Locking option. | 25364 The [ENOSYS] error condition has been removed as stubs need not be provided if an 25365 implementation does not support the Range Memory Locking option. | 1284 Technical Standard (2000) (Draft July 31, 2000) System Interfaces mlockall( ) 25366 NAME 25367 mlockall, munlockall - lock/unlock the address space of a process (REALTIME) 25368 SYNOPSIS 25369 ML #include 25370 int mlockall(int flags); 25371 int munlockall(void); 25372 25373 DESCRIPTION 25374 The mlockall( ) function shall cause all of the pages mapped by the address space of a process to 25375 be memory-resident until unlocked or until the process exits or execs another process image. The 25376 flags argument determines whether the pages to be locked are those currently mapped by the 25377 address space of the process, those that are mapped in the future, or both. The flags argument is 25378 constructed from the bitwise-inclusive OR of one or more of the following symbolic constants, 25379 defined in : 25380 MCL_CURRENT Lock all of the pages currently mapped into the address space of the process. 25381 MCL_FUTURE Lock all of the pages that become mapped into the address space of the 25382 process in the future, when those mappings are established. 25383 If MCL_FUTURE is specified, and the automatic locking of future mappings eventually causes 25384 the amount of locked memory to exceed the amount of available physical memory or any other | 25385 implementation-defined limit, the behavior is implementation-defined. The manner in which the | 25386 implementation informs the application of these situations is also implementation-defined. | 25387 The munlockall( ) function unlocks all currently mapped pages of the address space of the 25388 process. Any pages that become mapped into the address space of the process after a call to 25389 munlockall( ) shall not be locked, unless there is an intervening call to mlockall( ) specifying 25390 MCL_FUTURE or a subsequent call to mlockall( ) specifying MCL_CURRENT. If pages mapped 25391 into the address space of the process are also mapped into the address spaces of other processes 25392 and are locked by those processes, the locks established by the other processes are unaffected by 25393 a call by this process to munlockall( ). 25394 Upon successful return from the mlockall( ) function that specifies MCL_CURRENT, all currently 25395 mapped pages of the process' address space shall be memory-resident and locked. Upon return 25396 from the munlockall( ) function, all currently mapped pages of the process' address space shall be 25397 unlocked with respect to the process' address space. The memory residency of unlocked pages is 25398 unspecified. 25399 The appropriate privilege is required to lock process memory with mlockall( ). 25400 RETURN VALUE 25401 Upon successful completion, the mlockall( ) function shall return a value of zero. Otherwise, no 25402 additional memory shall be locked, and the function shall return a value of -1 and set errno to 25403 indicate the error. The effect of failure of mlockall( ) on previously existing locks in the address 25404 space is unspecified. 25405 If it is supported by the implementation, the munlockall( ) function shall always return a value of 25406 zero. Otherwise, the function shall return a value of -1 and set errno to indicate the error. 25407 ERRORS 25408 The mlockall( ) function shall fail if: 25409 [EAGAIN] Some or all of the memory identified by the operation could not be locked | 25410 when the call was made. System Interfaces, Issue 6 1285 mlockall( ) System Interfaces 25411 [EINVAL] The flags argument is zero, or includes unimplemented flags. | 25412 The mlockall( ) function may fail if: 25413 [ENOMEM] Locking all of the pages currently mapped into the address space of the | 25414 process would exceed an implementation-defined limit on the amount of | 25415 memory that the process may lock. 25416 [EPERM] The calling process does not have the appropriate privilege to perform the | 25417 requested operation. 25418 EXAMPLES 25419 None. 25420 APPLICATION USAGE 25421 None. 25422 RATIONALE 25423 None. 25424 FUTURE DIRECTIONS 25425 None. 25426 SEE ALSO 25427 exec, exit( ), fork( ), mlock( ), munmap( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 25428 25429 CHANGE HISTORY 25430 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 25431 Issue 6 25432 The mlockall( ) and munlockall( ) functions are marked as part of the Process Memory Locking | 25433 option. | 25434 The [ENOSYS] error condition has been removed as stubs need not be provided if an 25435 implementation does not support the Process Memory Locking option. | 1286 Technical Standard (2000) (Draft July 31, 2000) System Interfaces mmap( ) 25436 NAME 25437 mmap - map pages of memory 25438 SYNOPSIS 25439 MF|SHM #include 25440 void *mmap(void *addr, size_t len, int prot, int flags, 25441 int fildes, off_t off); 25442 25443 DESCRIPTION 25444 The mmap( ) function shall establish a mapping between a process' address space and a file, | 25445 TYM shared memory object, or typed memory object. The format of the call is as follows: | 25446 pa=mmap(addr, len, prot, flags, fildes, off); 25447 The mmap( ) function establishes a mapping between the address space of the process at an 25448 address pa for len bytes to the memory object represented by the file descriptor fildes at offset off 25449 for len bytes. The value of pa is an implementation-defined function of the parameter addr and | 25450 the values of flags, further described below. A successful mmap( ) call shall return pa as its result. 25451 The address range starting at pa and continuing for len bytes shall be legitimate for the possible 25452 (not necessarily current) address space of the process. The range of bytes starting at off and 25453 continuing for len bytes shall be legitimate for the possible (not necessarily current) offsets in the | 25454 TYM file, shared memory object, or typed memory object represented by fildes. | 25455 TYM If fildes represents a typed memory object opened with either the 25456 POSIX_TYPED_MEM_ALLOCATE flag or the POSIX_TYPED_MEM_ALLOCATE_CONTIG 25457 flag, the memory object to be mapped shall be that portion of the typed memory object allocated 25458 by the implementation as specified below. In this case, if off is non-zero, the behavior of mmap( ) 25459 is undefined. If fildes refers to a valid typed memory object that is not accessible from the calling 25460 process, mmap( ) shall fail. 25461 The mapping established by mmap( ) replaces any previous mappings for those whole pages 25462 containing any part of the address space of the process starting at pa and continuing for len 25463 bytes. 25464 If the size of the mapped file changes after the call to mmap( ) as a result of some other operation 25465 on the mapped file, the effect of references to portions of the mapped region that correspond to 25466 added or removed portions of the file is unspecified. 25467 TYM The mmap( ) function is supported for regular files, shared memory objects, and typed memory | 25468 objects. Support for any other type of file is unspecified. | 25469 The parameter prot determines whether read, write, execute, or some combination of accesses 25470 are permitted to the data being mapped. The prot should be either PROT_NONE or the bitwise- 25471 inclusive OR of one or more of the other flags in the following table, defined in the header 25472 . 25473 ____________________________________________ 25474 _ Symbolic Constant Description ___________________________________________ 25475 PROT_READ Data can be read. 25476 PROT_WRITE Data can be written. 25477 PROT_EXEC Data can be executed. 25478 _ PROT_NONE Data cannot be accessed. ___________________________________________ 25479 If an implementation cannot support the combination of access types specified by prot, the call 25480 MPR to mmap( ) fails. An implementation may permit accesses other than those specified by prot; | 25481 however, if the Memory Protection option is supported, the implementation shall not permit a | System Interfaces, Issue 6 1287 mmap( ) System Interfaces 25482 write to succeed where PROT_WRITE has not been set or shall not permit any access where | 25483 PROT_NONE alone has been set. The implementation shall support at least the following values | 25484 of prot: PROT_NONE, PROT_READ, PROT_WRITE, and the bitwise-inclusive OR of 25485 PROT_READ and PROT_WRITE. If the Memory Protection option is not supported, the result of | 25486 any access that conflicts with the specified protection is undefined. The file descriptor fildes shall | 25487 have been opened with read permission, regardless of the protection options specified. If 25488 PROT_WRITE is specified, the application shall ensure that it has opened the file descriptor 25489 fildes with write permission unless MAP_PRIVATE is specified in the flags parameter as 25490 described below. 25491 The parameter flags provides other information about the handling of the mapped data. The 25492 value of flags is the bitwise-inclusive OR of these options, defined in : 25493 __________________________________________ 25494 _ Symbolic Constant Description _________________________________________ 25495 MAP_SHARED Changes are shared. 25496 MAP_PRIVATE Changes are private. 25497 _ MAP_FIXED Interpret addr exactly. _________________________________________ 25498 Implementations that do not support the Memory Mapped Files option are not required to | 25499 XSI support MAP_PRIVATE. It is implementation-defined whether MAP_FIXED shall be supported. | 25500 MAP_FIXED shall be supported on XSI-conformant systems. 25501 MAP_SHARED and MAP_PRIVATE describe the disposition of write references to the memory 25502 object. If MAP_SHARED is specified, write references change the underlying object. If 25503 MAP_PRIVATE is specified, modifications to the mapped data by the calling process shall be 25504 visible only to the calling process and shall not change the underlying object. It is unspecified 25505 whether modifications to the underlying object done after the MAP_PRIVATE mapping is 25506 established are visible through the MAP_PRIVATE mapping. Either MAP_SHARED or 25507 MAP_PRIVATE can be specified, but not both. The mapping type is retained across fork( ). 25508 TYM When fildes represents a typed memory object opened with either the 25509 POSIX_TYPED_MEM_ALLOCATE flag or the POSIX_TYPED_MEM_ALLOCATE_CONTIG 25510 flag, mmap( ) shall, if there are enough resources available, map len bytes allocated from the 25511 corresponding typed memory object which were not previously allocated to any process in any 25512 processor that may access that typed memory object. If there are not enough resources available, 25513 the function shall fail. If fildes represents a typed memory object opened with the 25514 POSIX_TYPED_MEM_ALLOCATE_CONTIG flag, these allocated bytes shall be contiguous 25515 within the typed memory object. If fildes represents a typed memory object opened with the 25516 POSIX_TYPED_MEM_ALLOCATE flag, these allocated bytes may be composed of non- 25517 contiguous fragments within the typed memory object. If fildes represents a typed memory 25518 object opened with neither the POSIX_TYPED_MEM_ALLOCATE_CONTIG flag nor the 25519 POSIX_TYPED_MEM_ALLOCATE flag, len bytes starting at offset off within the typed memory 25520 object are mapped, exactly as when mapping a file or shared memory object. In this case, if two 25521 processes map an area of typed memory using the same off and len values and using file 25522 descriptors that refer to the same memory pool (either from the same port or from a different 25523 port), both processes shall map the same region of storage. 25524 When MAP_FIXED is set in the flags argument, the implementation is informed that the value of 25525 pa shall be addr, exactly. If MAP_FIXED is set, mmap( ) may return MAP_FAILED and set errno to | 25526 [EINVAL]. If a MAP_FIXED request is successful, the mapping established by mmap( ) replaces 25527 any previous mappings for the process' pages in the range [pa,pa+len). | 25528 When MAP_FIXED is not set, the implementation uses addr in an implementation-defined | 25529 manner to arrive at pa. The pa so chosen shall be an area of the address space that the | 1288 Technical Standard (2000) (Draft July 31, 2000) System Interfaces mmap( ) 25530 implementation deems suitable for a mapping of len bytes to the file. All implementations 25531 interpret an addr value of 0 as granting the implementation complete freedom in selecting pa, 25532 subject to constraints described below. A non-zero value of addr is taken to be a suggestion of a 25533 process address near which the mapping should be placed. When the implementation selects a 25534 value for pa, it never places a mapping at address 0, nor does it replace any extant mapping. 25535 The off argument is constrained to be aligned and sized according to the value returned by | 25536 sysconf( ) when passed _SC_PAGESIZE or _SC_PAGE_SIZE. When MAP_FIXED is specified, the 25537 application shall ensure that the argument addr also meets these constraints. The 25538 implementation performs mapping operations over whole pages. Thus, while the argument len 25539 need not meet a size or alignment constraint, the implementation shall include, in any mapping 25540 operation, any partial page specified by the range [pa,pa+len). | 25541 The system shall always zero-fill any partial page at the end of an object. Further, the system | 25542 shall never write out any modified portions of the last page of an object which are beyond its | 25543 MPR end. References within the address range starting at pa and continuing for len bytes to whole | 25544 pages following the end of an object shall result in delivery of a SIGBUS signal. | 25545 An implementation may generate SIGBUS signals when a reference would cause an error in the | 25546 mapped object, such as out-of-space condition. | 25547 The mmap( ) function adds an extra reference to the file associated with the file descriptor fildes | 25548 which is not removed by a subsequent close( ) on that file descriptor. This reference is removed 25549 when there are no more mappings to the file. | 25550 The st_atime field of the mapped file may be marked for update at any time between the mmap( ) 25551 call and the corresponding munmap( ) call. The initial read or write reference to a mapped region 25552 shall cause the file's st_atime field to be marked for update if it has not already been marked for 25553 update. 25554 The st_ctime and st_mtime fields of a file that is mapped with MAP_SHARED and PROT_WRITE 25555 shall be marked for update at some point in the interval between a write reference to the 25556 mapped region and the next call to msync( ) with MS_ASYNC or MS_SYNC for that portion of 25557 the file by any process. If there is no such call and if the underlying file is modified as a result of 25558 a write reference, then these fields shall be marked for update at some time after the write 25559 reference. 25560 There may be implementation-defined limits on the number of memory regions that can be | 25561 mapped (per process or per system). | 25562 XSI If such a limit is imposed, whether the number of memory regions that can be mapped by a 25563 process is decreased by the use of shmat( ) is implementation-defined. | 25564 If mmap( ) fails for reasons other than [EBADF], [EINVAL], or [ENOTSUP], some of the 25565 mappings in the address range starting at addr and continuing for len bytes may have been 25566 unmapped. 25567 RETURN VALUE 25568 Upon successful completion, the mmap( ) function shall return the address at which the mapping 25569 was placed (pa); otherwise, it shall return a value of MAP_FAILED and set errno to indicate the 25570 error. The symbol MAP_FAILED is defined in the header . No successful return 25571 from mmap( ) shall return the value MAP_FAILED. 25572 ERRORS 25573 The mmap( ) function shall fail if: 25574 [EACCES] The fildes argument is not open for read, regardless of the protection specified, 25575 or fildes is not open for write and PROT_WRITE was specified for a System Interfaces, Issue 6 1289 mmap( ) System Interfaces 25576 MAP_SHARED type mapping. 25577 ML [EAGAIN] The mapping could not be locked in memory, if required by mlockall( ), due to 25578 a lack of resources. 25579 [EBADF] The fildes argument is not a valid open file descriptor. | 25580 [EINVAL] The addr argument (if MAP_FIXED was specified) or off is not a multiple of | 25581 the page size as returned by sysconf( ), or are considered invalid by the 25582 implementation. | 25583 [EINVAL] The value of flags is invalid (neither MAP_PRIVATE nor MAP_SHARED is 25584 set). | 25585 [EMFILE] The number of mapped regions would exceed an implementation-defined | 25586 limit (per process or per system). | 25587 [ENODEV] The fildes argument refers to a file whose type is not supported by mmap( ). 25588 [ENOMEM] MAP_FIXED was specified, and the range [addr,addr+len) exceeds that allowed 25589 for the address space of a process; or, if MAP_FIXED was not specified and 25590 there is insufficient room in the address space to effect the mapping. 25591 ML [ENOMEM] The mapping could not be locked in memory, if required by mlockall( ), 25592 because it would require more space than the system is able to supply. 25593 MAP_FIXED or MAP_PRIVATE was specified in the flags argument and the 25594 implementation does not support this functionality. 25595 TYM [ENOMEM] Not enough unallocated memory resources remain in the typed memory 25596 object designated by fildes to allocate len bytes. 25597 [ENOTSUP] The implementation does not support the combination of accesses requested 25598 in the prot argument. 25599 [ENXIO] Addresses in the range [off,off+len) are invalid for the object specified by fildes. 25600 [ENXIO] MAP_FIXED was specified in flags and the combination of addr, len, and off is 25601 invalid for the object specified by fildes. 25602 TYM [ENXIO] The fildes argument refers to a typed memory object that is not accessible from 25603 the calling process. | 25604 [EOVERFLOW] The file is a regular file and the value of off plus len exceeds the offset | 25605 maximum established in the open file description associated with fildes. | 25606 EXAMPLES 25607 None. 25608 APPLICATION USAGE 25609 Use of mmap( ) may reduce the amount of memory available to other memory allocation 25610 functions. 25611 Use of MAP_FIXED may result in unspecified behavior in further use of malloc( ) and shmat( ). 25612 The use of MAP_FIXED is discouraged, as it may prevent an implementation from making the 25613 most effective use of resources. 25614 The application must ensure correct synchronization when using mmap( ) in conjunction with 25615 any other file access method, such as read( ) and write( ), standard input/output, and shmat( ). 25616 The mmap( ) function allows access to resources via address space manipulations, instead of 25617 read( )/write( ). Once a file is mapped, all a process has to do to access it is use the data at the 1290 Technical Standard (2000) (Draft July 31, 2000) System Interfaces mmap( ) 25618 address to which the file was mapped. So, using pseudo-code to illustrate the way in which an 25619 existing program might be changed to use mmap( ), the following: 25620 fildes = open(...) 25621 lseek(fildes, some_offset) 25622 read(fildes, buf, len) 25623 /* Use data in buf. */ 25624 becomes: 25625 fildes = open(...) 25626 address = mmap(0, len, PROT_READ, MAP_PRIVATE, fildes, some_offset) 25627 /* Use data at address. */ 25628 The [EINVAL] error above is marked EX because it is defined as an optional error in the POSIX 25629 Realtime Extension. 25630 RATIONALE 25631 After considering several other alternatives, it was decided to adopt the mmap( ) definition found 25632 in SVR4 for mapping memory objects into process address spaces. The SVR4 definition is 25633 minimal, in that it describes only what has been built, and what appears to be necessary for a 25634 general and portable mapping facility. 25635 Note that while mmap( ) was first designed for mapping files, it is actually a general-purpose 25636 mapping facility. It can be used to map any appropriate object, such as memory, files, devices, 25637 and so on, into the address space of a process. 25638 When a mapping is established, it is possible that the implementation may need to map more 25639 than is requested into the address space of the process because of hardware requirements. An 25640 application, however, cannot count on this behavior. Implementations that do not use a paged 25641 architecture may simply allocate a common memory region and return the address of it; such 25642 implementations probably do not allocate any more than is necessary. References past the end of 25643 the requested area are unspecified. 25644 If an application requests a mapping that would overlay existing mappings in the process, it 25645 might be desirable that an implementation detect this and inform the application. However, the 25646 default, portable (not MAP_FIXED) operation does not overlay existing mappings. On the other 25647 hand, if the program specifies a fixed address mapping (which requires some implementation 25648 knowledge to determine a suitable address, if the function is supported at all), then the program 25649 is presumed to be successfully managing its own address space and should be trusted when it 25650 asks to map over existing data structures. Furthermore, it is also desirable to make as few system 25651 calls as possible, and it might be considered onerous to require an munmap( ) before an mmap( ) 25652 to the same address range. This volume of IEEE Std. 1003.1-200x specifies that the new 25653 mappings replace any existing mappings, following existing practice in this regard. 25654 It is not expected, when the Memory Protection option is supported, that all hardware 25655 implementations are able to support all combinations of permissions at all addresses. When this 25656 option is supported, implementations are required to disallow write access to mappings without 25657 write permission and to disallow access to mappings without any access permission. Other than 25658 these restrictions, implementations may allow access types other than those requested by the 25659 application. For example, if the application requests only PROT_WRITE, the implementation 25660 may also allow read access. A call to mmap( ) fails if the implementation cannot support allowing 25661 all the access requested by the application. For example, some implementations cannot support 25662 a request for both write access and execute access simultaneously. All implementations 25663 supporting the Memory Protection option must support requests for no access, read access, 25664 write access, and both read and write access. Strictly conforming code must only rely on the 25665 required checks. These restrictions allow for portability across a wide range of hardware. System Interfaces, Issue 6 1291 mmap( ) System Interfaces 25666 The MAP_FIXED address treatment is likely to fail for non-page-aligned values and for certain 25667 architecture-dependent address ranges. Conforming implementations cannot count on being 25668 able to choose address values for MAP_FIXED without utilizing non-portable, implementation- | 25669 defined knowledge. Nonetheless, MAP_FIXED is provided as a standard interface conforming to | 25670 existing practice for utilizing such knowledge when it is available. 25671 Similarly, in order to allow implementations that do not support virtual addresses, support for 25672 directly specifying any mapping addresses via MAP_FIXED is not required and thus a 25673 conforming application may not count on it. 25674 The MAP_PRIVATE function can be implemented efficiently when memory protection hardware 25675 is available. When such hardware is not available, implementations can implement such 25676 ``mappings'' by simply making a real copy of the relevant data into process private memory, 25677 though this tends to behave similarly to read( ). 25678 The function has been defined to allow for many different models of using shared memory. 25679 However, all uses are not equally portable across all machine architectures. In particular, the 25680 mmap( ) function allows the system as well as the application to specify the address at which to 25681 map a specific region of a memory object. The most portable way to use the function is always to 25682 let the system choose the address, specifying NULL as the value for the argument addr and not 25683 to specify MAP_FIXED. 25684 If it is intended that a particular region of a memory object be mapped at the same address in a 25685 group of processes (on machines where this is even possible), then MAP_FIXED can be used to 25686 pass in the desired mapping address. The system can still be used to choose the desired address 25687 if the first such mapping is made without specifying MAP_FIXED, and then the resulting 25688 mapping address can be passed to subsequent processes for them to pass in via MAP_FIXED. 25689 The availability of a specific address range cannot be guaranteed, in general. 25690 The mmap( ) function can be used to map a region of memory that is larger than the current size 25691 of the object. Memory access within the mapping but beyond the current end of the underlying 25692 objects may result in SIGBUS signals being sent to the process. The reason for this is that the size 25693 of the object can be manipulated by other processes and can change at any moment. The 25694 implementation should tell the application that a memory reference is outside the object where 25695 this can be detected; otherwise, written data may be lost and read data may not reflect actual 25696 data in the object. 25697 Note that references beyond the end of the object do not extend the object as the new end cannot 25698 be determined precisely by most virtual memory hardware. Instead, the size can be directly 25699 manipulated by ftruncate( ). 25700 Process memory locking does apply to shared memory regions, and the MEMLOCK_FUTURE 25701 argument to memlockall( ) can be relied upon to cause new shared memory regions to be 25702 automatically locked. 25703 Existing implementations of mmap( ) return the value -1 when unsuccessful. Since the casting of 25704 this value to type void* cannot be guaranteed by the ISO C standard to be distinct from a 25705 successful value, this volume of IEEE Std. 1003.1-200x defines the symbol MAP_FAILED, which 25706 a conforming implementation does not return as the result of a successful call. 25707 FUTURE DIRECTIONS 25708 None. 25709 SEE ALSO 25710 exec, fcntl( ), fork( ), lockf( ), msync( ), munmap( ), mprotect( ), posix_typed_mem_open( ), shmat( ), 25711 sysconf( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 1292 Technical Standard (2000) (Draft July 31, 2000) System Interfaces mmap( ) 25712 CHANGE HISTORY 25713 First released in Issue 4, Version 2. 25714 Issue 5 25715 Moved from X/OPEN UNIX extension to BASE. 25716 Aligned with mmap( ) in the POSIX Realtime Extension as follows: 25717 * The DESCRIPTION is extensively reworded. 25718 * The [EAGAIN] and [ENOTSUP] mandatory error conditions are added. 25719 * New cases of [ENOMEM] and [ENXIO] are added as mandatory error conditions. 25720 * The value returned on failure is the value of the constant MAP_FAILED; this was previously 25721 defined as -1. 25722 Large File Summit extensions are added. 25723 Issue 6 25724 The mmap( ) function is marked as part of the Memory Mapped Files option. | 25725 The Open Group corrigenda item U028/6 has been applied, changing (void *)-1 to 25726 MAP_FAILED. 25727 The following new requirements on POSIX implementations derive from alignment with the 25728 Single UNIX Specification: 25729 * The DESCRIPTION is updated to described the use of MAP_FIXED. 25730 * The DESCRIPTION is updated to describe the addition of an extra reference to the file 25731 associated with the file descriptor passed to mmap( ). 25732 * The DESCRIPTION is updated to state that there may be implementation-defined limits on | 25733 the number of memory regions that can be mapped. | 25734 * The DESCRIPTION is updated to describe constraints on the alignment and size of the off 25735 argument. 25736 * The [EINVAL] and [EMFILE] error conditions are added. 25737 * The [EOVERFLOW] error condition is added. This change is to support large files. 25738 The following changes are made for alignment with the ISO POSIX-1: 1996 standard: 25739 * The DESCRIPTION is updated to describe the cases when MAP_PRIVATE and MAP_FIXED 25740 need not be supported. 25741 The following changes are made for alignment with IEEE Std. 1003.1j-2000: 25742 * Semantics for typed memory objects are added to the DESCRIPTION. 25743 * New [ENOMEM] and [ENXIO] errors are added to the ERRORS section. 25744 * The posix_typed_mem_open( ) function is added to the SEE ALSO section. 25745 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1293 modf( ) System Interfaces 25746 NAME 25747 modf, modff, modfl - decompose a floating-point number | 25748 SYNOPSIS 25749 #include 25750 double modf(double x, double *iptr); 25751 float modff(float value, float *iptr); | 25752 long double modfl(long double value, long double *iptr); | 25753 DESCRIPTION | 25754 CX The functionality described on this reference page is aligned with the ISO C standard. Any 25755 conflict between the requirements described here and the ISO C standard is unintentional. This 25756 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 25757 These functions shall break the argument x into integral and fractional parts, each of which has | 25758 the same sign as the argument. It stores the integral part as a double in the object pointed to by 25759 iptr. 25760 An application wishing to check for error situations should set errno to 0 before calling modf( ). If 25761 errno is non-zero on return, or the return value is NaN, an error has occurred. 25762 RETURN VALUE 25763 Upon successful completion, these functions shall return the signed fractional part of x. | 25764 XSI If x is NaN, NaN shall be returned, errno may be set to [EDOM], and *iptr shall be set to NaN. 25765 If the correct value would cause underflow, 0 shall be returned and errno may be set to 25766 [ERANGE]. 25767 ERRORS 25768 These functions may fail if: | 25769 XSI [EDOM] The value of x is NaN. | 25770 [ERANGE] The result underflows. | 25771 XSI No other errors shall occur. 25772 EXAMPLES 25773 None. 25774 APPLICATION USAGE 25775 The modf( ) function computes the function result and *iptr such that: 25776 a = modf(x, &iptr) 25777 x == a+iptr 25778 allowing for the usual floating point inaccuracies. 25779 RATIONALE 25780 None. 25781 FUTURE DIRECTIONS 25782 None. 25783 SEE ALSO 25784 frexp( ), isnan( ), ldexp( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 1294 Technical Standard (2000) (Draft July 31, 2000) System Interfaces modf( ) 25785 CHANGE HISTORY 25786 First released in Issue 1. Derived from Issue 1 of the SVID. | 25787 Issue 4 25788 References to matherr( ) are removed. 25789 The name of the first argument is changed from value to x. 25790 The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 25791 ISO C standard and to rationalize error handling in the mathematics functions. 25792 The return value specified for [EDOM] is marked as an extension. 25793 Issue 5 25794 The DESCRIPTION is updated to indicate how an application should check for an error. This 25795 text was previously published in the APPLICATION USAGE section. | 25796 Issue 6 | 25797 The modff( ) and modfl( ) functions are added for alignment with the ISO/IEC 9899: 1999 | 25798 standard. | System Interfaces, Issue 6 1295 mprotect( ) System Interfaces 25799 NAME 25800 mprotect - set protection of memory mapping 25801 SYNOPSIS 25802 MPR #include 25803 int mprotect(void *addr, size_t len, int prot); 25804 25805 DESCRIPTION 25806 The mprotect( ) function shall change the access protections to be that specified by prot for those 25807 whole pages containing any part of the address space of the process starting at address addr and 25808 continuing for len bytes. The parameter prot determines whether read, write, execute, or some 25809 combination of accesses are permitted to the data being mapped. The prot argument should be 25810 either PROT_NONE or the bitwise-inclusive OR of one or more of PROT_READ, PROT_WRITE, 25811 and PROT_EXEC. 25812 If an implementation cannot support the combination of access types specified by prot, the call 25813 to mprotect( ) shall fail. 25814 An implementation may permit accesses other than those specified by prot; however, no | 25815 implementation shall permit a write to succeed where PROT_WRITE has not been set or shall | 25816 permit any access where PROT_NONE alone has been set. Implementations shall support at | 25817 least the following values of prot: PROT_NONE, PROT_READ, PROT_WRITE, and the bitwise- | 25818 inclusive OR of PROT_READ and PROT_WRITE. If PROT_WRITE is specified, the application 25819 shall ensure that it has opened the mapped objects in the specified address range with write 25820 permission, unless MAP_PRIVATE was specified in the original mapping, regardless of whether 25821 the file descriptors used to map the objects have since been closed. 25822 The implementation shall require that addr be a multiple of the page size as returned by | 25823 sysconf( ). 25824 The behavior of this function is unspecified if the mapping was not established by a call to 25825 mmap( ). 25826 When mprotect( ) fails for reasons other than [EINVAL], the protections on some of the pages in 25827 the range [addr,addr+len) may have been changed. 25828 RETURN VALUE 25829 Upon successful completion, mprotect( ) shall return 0; otherwise, it shall return -1 and set errno 25830 to indicate the error. 25831 ERRORS 25832 The mprotect( ) function shall fail if: 25833 [EACCES] The prot argument specifies a protection that violates the access permission | 25834 the process has to the underlying memory object. 25835 [EAGAIN] The prot argument specifies PROT_WRITE over a MAP_PRIVATE mapping | 25836 and there are insufficient memory resources to reserve for locking the private 25837 page. | 25838 [EINVAL] The addr argument is not a multiple of the page size as returned by sysconf( ). | 25839 [ENOMEM] Addresses in the range [addr,addr+len) are invalid for the address space of a | 25840 process, or specify one or more pages which are not mapped. 25841 [ENOMEM] The prot argument specifies PROT_WRITE on a MAP_PRIVATE mapping, and 25842 it would require more space than the system is able to supply for locking the 25843 private pages, if required. 1296 Technical Standard (2000) (Draft July 31, 2000) System Interfaces mprotect( ) 25844 [ENOTSUP] The implementation does not support the combination of accesses requested | 25845 in the prot argument. 25846 EXAMPLES 25847 None. 25848 APPLICATION USAGE 25849 The [EINVAL] error above is marked EX because it is defined as an optional error in the POSIX 25850 Realtime Extension. 25851 RATIONALE 25852 None. 25853 FUTURE DIRECTIONS 25854 None. 25855 SEE ALSO 25856 mmap( ), sysconf( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 25857 CHANGE HISTORY 25858 First released in Issue 4, Version 2. 25859 Issue 5 25860 Moved from X/OPEN UNIX extension to BASE. 25861 Aligned with mprotect( ) in the POSIX Realtime Extension as follows: 25862 * The DESCRIPTION is largely reworded. 25863 * [ENOTSUP] and a second form of [ENOMEM] are added as mandatory error conditions. 25864 * [EAGAIN] is moved from the optional to the mandatory error conditions. 25865 Issue 6 25866 The mprotect( ) function is marked as part of the Memory Protection option. | 25867 The following new requirements on POSIX implementations derive from alignment with the 25868 Single UNIX Specification: 25869 * The DESCRIPTION is updated to state that implementations require addr to be a multiple of 25870 the page size as returned by sysconf( ). 25871 * The [EINVAL] error condition is added. 25872 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1297 mq_close( ) System Interfaces 25873 NAME 25874 mq_close - close a message queue (REALTIME) 25875 SYNOPSIS 25876 MSG #include 25877 int mq_close(mqd_t mqdes); 25878 25879 DESCRIPTION 25880 The mq_close( ) function shall remove the association between the message queue descriptor, 25881 mqdes, and its message queue. The results of using this message queue descriptor after 25882 successful return from this mq_close( ), and until the return of this message queue descriptor 25883 from a subsequent mq_open( ), are undefined. 25884 If the process has successfully attached a notification request to the message queue via this 25885 mqdes, this attachment shall be removed, and the message queue is available for another process 25886 to attach for notification. 25887 RETURN VALUE 25888 Upon successful completion, the mq_close( ) function shall return a value of zero; otherwise, the 25889 function shall return a value of -1 and set errno to indicate the error. 25890 ERRORS 25891 The mq_close( ) function shall fail if: 25892 [EBADF] The mqdes argument is not a valid message queue descriptor. | 25893 EXAMPLES 25894 None. 25895 APPLICATION USAGE 25896 None. 25897 RATIONALE 25898 None. 25899 FUTURE DIRECTIONS 25900 None. 25901 SEE ALSO 25902 mq_open( ), mq_unlink( ), msgctl( ), msgget( ), msgrcv( ), msgsnd( ), the Base Definitions volume of | 25903 IEEE Std. 1003.1-200x, | 25904 CHANGE HISTORY 25905 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 25906 Issue 6 25907 The mq_close( ) function is marked as part of the Message Passing option. | 25908 The [ENOSYS] error condition has been removed as stubs need not be provided if an 25909 implementation does not support the Message Passing option. | 1298 Technical Standard (2000) (Draft July 31, 2000) System Interfaces mq_getattr( ) 25910 NAME 25911 mq_getattr - get message queue attributes (REALTIME) 25912 SYNOPSIS 25913 MSG #include 25914 int mq_getattr(mqd_t mqdes, struct mq_attr *mqstat); 25915 25916 DESCRIPTION 25917 The mqdes argument specifies a message queue descriptor. 25918 The mq_getattr( ) function is used to get status information and attributes of the message queue 25919 and the open message queue description associated with the message queue descriptor. 25920 The results are returned in the mq_attr structure referenced by the mqstat argument. 25921 Upon return, the following members have the values associated with the open message queue 25922 description as set when the message queue was opened and as modified by subsequent 25923 mq_setattr( ) calls: mq_flags. 25924 The following attributes of the message queue shall be returned as set at message queue 25925 creation: mq_maxmsg, mq_msgsize. 25926 Upon return, the following members within the mq_attr structure referenced by the mqstat 25927 argument are set to the current state of the message queue: 25928 mq_curmsgs The number of messages currently on the queue. 25929 RETURN VALUE 25930 Upon successful completion, the mq_getattr( ) function shall return zero. Otherwise, the function 25931 shall return -1 and set errno to indicate the error. 25932 ERRORS 25933 The mq_getattr( ) function shall fail if: 25934 [EBADF] The mqdes argument is not a valid message queue descriptor. | 25935 EXAMPLES 25936 None. 25937 APPLICATION USAGE 25938 None. 25939 RATIONALE 25940 None. 25941 FUTURE DIRECTIONS 25942 None. 25943 SEE ALSO 25944 mq_open( ), mq_send( ), mq_setattr( ), mq_timedsend( ), msgctl( ), msgget( ), msgrcv( ), msgsnd( ), the | 25945 Base Definitions volume of IEEE Std. 1003.1-200x, | 25946 CHANGE HISTORY 25947 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 25948 Issue 6 25949 The mq_getattr( ) function is marked as part of the Message Passing option. | 25950 The [ENOSYS] error condition has been removed as stubs need not be provided if an 25951 implementation does not support the Message Passing option. | System Interfaces, Issue 6 1299 mq_getattr( ) System Interfaces 25952 The mq_timedsend( ) function is added to the SEE ALSO section for alignment with 25953 IEEE Std. 1003.1d-1999. 1300 Technical Standard (2000) (Draft July 31, 2000) System Interfaces mq_notify( ) 25954 NAME 25955 mq_notify - notify process that a message is available (REALTIME) 25956 SYNOPSIS 25957 MSG #include 25958 int mq_notify(mqd_t mqdes, const struct sigevent *notification); 25959 25960 DESCRIPTION 25961 If the argument notification is not NULL, this function registers the calling process to be notified 25962 of message arrival at an empty message queue associated with the specified message queue 25963 descriptor, mqdes. The notification specified by the notification argument shall be sent to the 25964 process when the message queue transitions from empty to non-empty. At any time, only one 25965 process may be registered for notification by a message queue. If the calling process or any other 25966 process has already registered for notification of message arrival at the specified message queue, 25967 subsequent attempts to register for that message queue fail. 25968 If notification is NULL and the process is currently registered for notification by the specified 25969 message queue, the existing registration is removed. 25970 When the notification is sent to the registered process, its registration shall be removed. The 25971 message queue shall then be available for registration. 25972 If a process has registered for notification of message arrival at a message queue and some 25973 thread is blocked in mq_receive( ) waiting to receive a message when a message arrives at the 25974 queue, the arriving message satisfies the appropriate mq_receive( ). The resulting behavior is as if 25975 the message queue remains empty, and no notification is sent. 25976 RETURN VALUE 25977 Upon successful completion, the mq_notify( ) function shall return a value of zero; otherwise, the 25978 function shall return a value of -1 and set errno to indicate the error. 25979 ERRORS 25980 The mq_notify( ) function shall fail if: 25981 [EBADF] The mqdes argument is not a valid message queue descriptor. | 25982 [EBUSY] A process is already registered for notification by the message queue. | 25983 EXAMPLES 25984 None. 25985 APPLICATION USAGE 25986 None. 25987 RATIONALE 25988 None. 25989 FUTURE DIRECTIONS 25990 None. 25991 SEE ALSO 25992 mq_open( ), mq_send( ), mq_timedsend( ), msgctl( ), msgget( ), msgrcv( ), msgsnd( ), the Base | 25993 Definitions volume of IEEE Std. 1003.1-200x, | 25994 CHANGE HISTORY 25995 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. System Interfaces, Issue 6 1301 mq_notify( ) System Interfaces 25996 Issue 6 25997 The mq_notify( ) function is marked as part of the Message Passing option. | 25998 The [ENOSYS] error condition has been removed as stubs need not be provided if an 25999 implementation does not support the Message Passing option. | 26000 The mq_timedsend( ) function is added to the SEE ALSO section for alignment with 26001 IEEE Std. 1003.1d-1999. 1302 Technical Standard (2000) (Draft July 31, 2000) System Interfaces mq_open( ) 26002 NAME 26003 mq_open - open a message queue (REALTIME) 26004 SYNOPSIS 26005 MSG #include 26006 mqd_t mq_open(const char *name, int oflag, ...); 26007 26008 DESCRIPTION 26009 The mq_open( ) function shall establish the connection between a process and a message queue 26010 with a message queue descriptor. It creates an open message queue description that refers to the 26011 message queue, and a message queue descriptor that refers to that open message queue 26012 description. The message queue descriptor is used by other functions to refer to that message 26013 queue. The name argument points to a string naming a message queue. It is unspecified whether 26014 the name appears in the file system and is visible to other functions that take path names as 26015 arguments. The name argument conforms to the construction rules for a path name. If name 26016 begins with the slash character, then processes calling mq_open( ) with the same value of name 26017 refer to the same message queue object, as long as that name has not been removed. If name does 26018 not begin with the slash character, the effect is implementation-defined. The interpretation of | 26019 slash characters other than the leading slash character in name is implementation-defined. If the | 26020 name argument is not the name of an existing message queue and creation is not requested, 26021 mq_open( ) shall fail and return an error. 26022 A message queue descriptor may be implemented using a file descriptor, in which case | 26023 applications can open up to at least {OPEN_MAX} file and message queues. | 26024 The oflag argument requests the desired receive and/or send access to the message queue. The | 26025 requested access permission to receive messages or send messages is granted if the calling 26026 process would be granted read or write access, respectively, to an equivalently protected file. 26027 The value of oflag is the bitwise-inclusive OR of values from the following list. Applications 26028 specify exactly one of the first three values (access modes) below in the value of oflag: 26029 O_RDONLY Open the message queue for receiving messages. The process can use the 26030 returned message queue descriptor with mq_receive( ), but not mq_send( ). A 26031 message queue may be open multiple times in the same or different processes 26032 for receiving messages. 26033 O_WRONLY Open the queue for sending messages. The process can use the returned 26034 message queue descriptor with mq_send( ) but not mq_receive( ). A message 26035 queue may be open multiple times in the same or different processes for 26036 sending messages. 26037 O_RDWR Open the queue for both receiving and sending messages. The process can use 26038 any of the functions allowed for O_RDONLY and O_WRONLY. A message 26039 queue may be open multiple times in the same or different processes for 26040 sending messages. 26041 Any combination of the remaining flags may be specified in the value of oflag: 26042 O_CREAT This option is used to create a message queue, and it requires two additional 26043 arguments: mode, which is of type mode_t, and attr, which is a pointer to a 26044 mq_attr structure. If the path name name has already been used to create a 26045 message queue that still exists, then this flag has no effect, except as noted 26046 under O_EXCL. Otherwise, a message queue is created without any messages 26047 in it. The user ID of the message queue is set to the effective user ID of the 26048 process, and the group ID of the message queue is set to the effective group ID System Interfaces, Issue 6 1303 mq_open( ) System Interfaces 26049 of the process. The file permission bits are set to the value of mode. When bits 26050 in mode other than file permission bits are set, the effect is implementation- | 26051 defined. If attr is NULL, the message queue is created with implementation- | 26052 defined default message queue attributes. If attr is non-NULL and the calling | 26053 process has the appropriate privilege on name, the message queue mq_maxmsg 26054 and mq_msgsize attributes are set to the values of the corresponding members 26055 in the mq_attr structure referred to by attr. If attr is non-NULL, but the calling 26056 process does not have the appropriate privilege on name, the mq_open( ) 26057 function shall fail and return an error without creating the message queue. 26058 O_EXCL If O_EXCL and O_CREAT are set, mq_open( ) fails if the message queue name 26059 exists. The check for the existence of the message queue and the creation of | 26060 the message queue if it does not exist shall be atomic with respect to other | 26061 threads executing mq_open( ) naming the same name with O_EXCL and | 26062 O_CREAT set. If O_EXCL is set and O_CREAT is not set, the result is 26063 undefined. 26064 O_NONBLOCK The setting of this flag is associated with the open message queue description 26065 and determines whether a mq_send( ) or mq_receive( ) waits for resources or 26066 messages that are not currently available, or fails with errno set to [EAGAIN]; 26067 see mq_send( ) and mq_receive( ) for details. 26068 The mq_open( ) function does not add or remove messages from the queue. 26069 RETURN VALUE 26070 Upon successful completion, the function shall return a message queue descriptor; otherwise, 26071 the function shall return (mqd_t)-1 and set errno to indicate the error. 26072 ERRORS 26073 The mq_open( ) function shall fail if: 26074 [EACCES] The message queue exists and the permissions specified by oflag are denied, or | 26075 the message queue does not exist and permission to create the message queue 26076 is denied. 26077 [EEXIST] O_CREAT and O_EXCL are set and the named message queue already exists. | 26078 [EINTR] The mq_open( ) function was interrupted by a signal. | 26079 [EINVAL] The mq_open( ) function is not supported for the given name. | 26080 [EINVAL] O_CREAT was specified in oflag, the value of attr is not NULL, and either 26081 mq_maxmsg or mq_msgsize was less than or equal to zero. 26082 [EMFILE] Too many message queue descriptors or file descriptors are currently in use by | 26083 this process. 26084 [ENAMETOOLONG] | 26085 The length of the name argument exceeds {PATH_MAX} or a path name | 26086 component is longer than {NAME_MAX}. | 26087 [ENFILE] Too many message queues are currently open in the system. | 26088 [ENOENT] O_CREAT is not set and the named message queue does not exist. | 26089 [ENOSPC] There is insufficient space for the creation of the new message queue. | 1304 Technical Standard (2000) (Draft July 31, 2000) System Interfaces mq_open( ) 26090 EXAMPLES 26091 None. 26092 APPLICATION USAGE 26093 None. 26094 RATIONALE 26095 None. 26096 FUTURE DIRECTIONS 26097 None. 26098 SEE ALSO 26099 mq_close( ), mq_getattr( ), mq_receive( ), mq_send( ), mq_setattr( ), mq_timedreceive( ), mq_timedsend( ), 26100 mq_unlink( ), msgctl( ), msgget( ), msgrcv( ), msgsnd( ), the Base Definitions volume of | 26101 IEEE Std. 1003.1-200x, | 26102 CHANGE HISTORY 26103 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 26104 Issue 6 26105 The mq_open( ) function is marked as part of the Message Passing option. | 26106 The [ENOSYS] error condition has been removed as stubs need not be provided if an 26107 implementation does not support the Message Passing option. | 26108 The mq_timedreceive( ) and mq_timedsend( ) functions are added to the SEE ALSO section for 26109 alignment with IEEE Std. 1003.1d-1999. | 26110 The DESCRIPTION of O_EXCL is updated in response to IEEE PASC Interpretation 1003.1c #48. | System Interfaces, Issue 6 1305 mq_receive( ) System Interfaces 26111 NAME 26112 mq_receive, mq_timedreceive - receive a message from a message queue (REALTIME) 26113 SYNOPSIS 26114 MSG #include 26115 ssize_t mq_receive(mqd_t mqdes, char *msg_ptr, size_t msg_len, 26116 unsigned *msg_prio); | 26117 | 26118 MSG TMO #include 26119 #include 26120 ssize_t mq_timedreceive(mqd_t mqdes, char *restrict msg_ptr, | 26121 size_t msg_len, unsigned *restrict msg_prio, | 26122 const struct timespec *restrict abs_timeout); | 26123 | 26124 DESCRIPTION | 26125 The mq_receive( ) function is used to receive the oldest of the highest priority message(s) from the 26126 message queue specified by mqdes. If the size of the buffer in bytes, specified by the msg_len 26127 argument, is less than the mq_msgsize attribute of the message queue, the function shall fail and 26128 return an error. Otherwise, the selected message is removed from the queue and copied to the 26129 buffer pointed to by the msg_ptr argument. 26130 If the value of msg_len is greater than {SSIZE_MAX}, the result is implementation-defined. | 26131 If the argument msg_prio is not NULL, the priority of the selected message is stored in the 26132 location referenced by msg_prio. 26133 If the specified message queue is empty and O_NONBLOCK is not set in the message queue 26134 description associated with mqdes, mq_receive( ) blocks until a message is enqueued on the 26135 message queue or until mq_receive( ) is interrupted by a signal. If more than one thread is waiting 26136 to receive a message when a message arrives at an empty queue and the Priority Scheduling 26137 option is supported, then the thread of highest priority that has been waiting the longest shall be 26138 selected to receive the message. Otherwise, it is unspecified which waiting thread receives the 26139 message. If the specified message queue is empty and O_NONBLOCK is set in the message 26140 queue description associated with mqdes, no message is removed from the queue, and 26141 mq_receive( ) shall return an error. 26142 TMO The mq_timedreceive( ) function is used to receive the oldest of the highest priority messages from 26143 the message queue specified by mqdes as in the mq_receive( ) function. However, if 26144 O_NONBLOCK was not specified when the message queue was opened via the mq_open( ) 26145 function, and no message exists on the queue to satisfy the receive, the wait for such a message 26146 will be terminated when the specified timeout expires. If O_NONBLOCK is set, this function 26147 shall behave identically to mq_receive( ). 26148 The timeout expires when the absolute time specified by abs_timeout passes, as measured by the 26149 clock on which timeouts are based (that is, when the value of that clock equals or exceeds 26150 abs_timeout), or if the absolute time specified by abs_timeout has already been passed at the time 26151 of the call. If the Timers option is supported, the timeout is based on the CLOCK_REALTIME 26152 clock; if the Timers option is not supported, the timeout is based on the system clock as returned 26153 by the time( ) function. The resolution of the timeout is the resolution of the clock on which it is 26154 based. The timespec argument is defined as a structure in the header. 26155 Under no circumstance shall the operation fail with a timeout if a message can be removed from 26156 the message queue immediately. The validity of the abs_timeout parameter need not be checked 26157 if a message can be removed from the message queue immediately. 1306 Technical Standard (2000) (Draft July 31, 2000) System Interfaces mq_receive( ) 26158 RETURN VALUE 26159 TMO Upon successful completion, the mq_receive( ) and mq_timedreceive( ) functions shall return the 26160 length of the selected message in bytes and the message shall be removed from the queue. 26161 Otherwise, no message shall be removed from the queue, the functions shall return a value of -1, 26162 and set errno to indicate the error. 26163 ERRORS 26164 TMO The mq_receive( ) and mq_timedreceive( )functions shall fail if: 26165 [EAGAIN] O_NONBLOCK was set in the message description associated with mqdes, | 26166 and the specified message queue is empty. 26167 [EBADF] The mqdes argument is not a valid message queue descriptor open for reading. | 26168 [EMSGSIZE] The specified message buffer size, msg_len, is less than the message size | 26169 attribute of the message queue. 26170 TMO [EINTR] The mq_receive( ) or mq_timedreceive( )operation was interrupted by a signal. | 26171 TMO [EINVAL] The process or thread would have blocked, and the abs_timeout parameter | 26172 specified a nanoseconds field value less than zero or greater than or equal to 26173 1 000 million. 26174 TMO [ETIMEDOUT] The O_NONBLOCK flag was not set when the message queue was opened, 26175 but no message arrived on the queue before the specified timeout expired. 26176 TMO The mq_receive( ) and mq_timedreceive( )functions may fail if: 26177 [EBADMSG] The implementation has detected a data corruption problem with the | 26178 message. 26179 EXAMPLES 26180 None. 26181 APPLICATION USAGE 26182 None. 26183 RATIONALE 26184 None. 26185 FUTURE DIRECTIONS 26186 None. 26187 SEE ALSO 26188 mq_open( ), mq_send( ), mq_timedsend( ), msgctl( ), msgget( ), msgrcv( ), msgsnd( ), time( ), the Base | 26189 Definitions volume of IEEE Std. 1003.1-200x, , | 26190 CHANGE HISTORY 26191 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 26192 Issue 6 26193 The mq_receive( ) function is marked as part of the Message Passing option. | 26194 The Open Group corrigenda item U021/4 has been applied. The DESCRIPTION is changed to 26195 refer to msg_len rather than maxsize. 26196 The [ENOSYS] error condition has been removed as stubs need not be provided if an 26197 implementation does not support the Message Passing option. | 26198 The following new requirements on POSIX implementations derive from alignment with the 26199 Single UNIX Specification: System Interfaces, Issue 6 1307 mq_receive( ) System Interfaces 26200 * In this function it is possible for the return value to exceed the range of the type ssize_t (since 26201 size_t has a larger range of positive values than ssize_t). A sentence restricting the size of 26202 the size_t object is added to the description to resolve this conflict. 26203 The mq_timedreceive( ) function is added for alignment with IEEE Std. 1003.1d-1999. | 26204 The restrict keyword is added to the mq_timedreceive( ) prototype for alignment with the | 26205 ISO/IEC 9899: 1999 standard. | 26206 IEEE PASC Interpretation 1003.1 #109 is applied, correcting the return type for mq_timedreceive( ) | 26207 from int to ssize_t. | 1308 Technical Standard (2000) (Draft July 31, 2000) System Interfaces mq_send( ) 26208 NAME 26209 mq_send, mq_timedsend - send a message to a message queue (REALTIME) 26210 SYNOPSIS 26211 MSG #include 26212 int mq_send(mqd_t mqdes, const char *msg_ptr, size_t msg_len, 26213 unsigned msg_prio); | 26214 | 26215 MSG TMO #include 26216 #include 26217 int mq_timedsend(mqd_t mqdes, const char *msg_ptr, size_t msg_len, 26218 unsigned msg_prio, const struct timespec *abs_timeout); | 26219 | 26220 DESCRIPTION 26221 The mq_send( ) function shall add the message pointed to by the argument msg_ptr to the 26222 message queue specified by mqdes. The msg_len argument specifies the length of the message in 26223 bytes pointed to by msg_ptr. The value of msg_len is less than or equal to the mq_msgsize 26224 attribute of the message queue, or mq_send( ) shall fail. 26225 If the specified message queue is not full, mq_send( ) behaves as if the message shall be inserted 26226 into the message queue at the position indicated by the msg_prio argument. A message with a 26227 larger numeric value of msg_prio shall be inserted before messages with lower values of 26228 msg_prio. A message shall be inserted after other messages in the queue, if any, with equal 26229 msg_prio. The value of msg_prio shall be less than {MQ_PRIO_MAX}. 26230 If the specified message queue is full and O_NONBLOCK is not set in the message queue 26231 description associated with mqdes, mq_send( ) shall block until space becomes available to 26232 enqueue the message, or until mq_send( ) is interrupted by a signal. If more than one thread is 26233 waiting to send when space becomes available in the message queue and the Priority Scheduling 26234 option is supported, then the thread of the highest priority that has been waiting the longest 26235 shall be unblocked to send its message. Otherwise, it is unspecified which waiting thread is 26236 unblocked. If the specified message queue is full and O_NONBLOCK is set in the message 26237 queue description associated with mqdes, the message shall not be queued and mq_send( ) shall 26238 return an error. 26239 TMO The mq_timedsend( ) function adds a message to the message queue specified by mqdes in the 26240 manner defined for the mq_send( ) function. However, if the specified message queue is full and 26241 O_NONBLOCK is not set in the message queue description associated with mqdes, the wait for 26242 sufficient room in the queue shall be terminated when the specified timeout expires. If 26243 O_NONBLOCK is set in the message queue description, this function shall behave identically to 26244 mq_send( ). 26245 The timeout expires when the absolute time specified by abs_timeout passes, as measured by the 26246 clock on which timeouts are based (that is, when the value of that clock equals or exceeds 26247 abs_timeout), or if the absolute time specified by abs_timeout has already been passed at the time 26248 of the call. If the Timers option is supported, the timeout is based on the CLOCK_REALTIME 26249 clock; if the Timers option is not supported, the timeout is based on the system clock as returned 26250 by the time( ) function. The resolution of the timeout is the resolution of the clock on which it is 26251 based. The timespec argument is defined as a structure in the header. 26252 Under no circumstance shall the operation fail with a timeout if there is sufficient room in the 26253 queue to add the message immediately. The validity of the abs_timeout parameter need not be 26254 checked when there is sufficient room in the queue. System Interfaces, Issue 6 1309 mq_send( ) System Interfaces 26255 RETURN VALUE 26256 TMO Upon successful completion, the mq_send( ) and mq_timedsend( ) functions shall return a value of 26257 zero. Otherwise, no message shall be enqueued, the functions shall return -1, and errno shall be 26258 set to indicate the error. 26259 ERRORS 26260 TMO The mq_send( ) and mq_timedsend( )functions shall fail if: 26261 [EAGAIN] The O_NONBLOCK flag is set in the message queue description associated | 26262 with mqdes, and the specified message queue is full. 26263 [EBADF] The mqdes argument is not a valid message queue descriptor open for writing. | 26264 TMO [EINTR] A signal interrupted the call to mq_send( ) or mq_timedsend( ). | 26265 [EINVAL] The value of msg_prio was outside the valid range. | 26266 TMO [EINVAL] The process or thread would have blocked, and the abs_timeout parameter | 26267 specified a nanoseconds field value less than zero or greater than or equal to 26268 1 000 million. 26269 [EMSGSIZE] The specified message length, msg_len, exceeds the message size attribute of | 26270 the message queue. 26271 TMO [ETIMEDOUT] The O_NONBLOCK flag was not set when the message queue was opened, 26272 but the timeout expired before the message could be added to the queue. | 26273 EXAMPLES 26274 None. 26275 APPLICATION USAGE 26276 The value of the symbol {MQ_PRIO_MAX} limits the number of priority levels supported by the 26277 application. Message priorities range from 0 to {MQ_PRIO_MAX}-1. 26278 RATIONALE 26279 None. 26280 FUTURE DIRECTIONS 26281 None. 26282 SEE ALSO 26283 mq_open( ), mq_receive( ), mq_setattr( ), mq_timedreceive( ), time( ), the Base Definitions volume of | 26284 IEEE Std. 1003.1-200x, , | 26285 CHANGE HISTORY 26286 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 26287 Issue 6 26288 The mq_send( ) function is marked as part of the Message Passing option. | 26289 The [ENOSYS] error condition has been removed as stubs need not be provided if an 26290 implementation does not support the Message Passing option. | 26291 The mq_timedsend( ) function is added for alignment with IEEE Std. 1003.1d-1999. 1310 Technical Standard (2000) (Draft July 31, 2000) System Interfaces mq_setattr( ) 26292 NAME 26293 mq_setattr - set message queue attributes (REALTIME) 26294 SYNOPSIS 26295 MSG #include 26296 int mq_setattr(mqd_t mqdes, const struct mq_attr *restrict mqstat, | 26297 struct mq_attr *restrict omqstat); | 26298 | 26299 DESCRIPTION 26300 The mq_setattr( ) function is used to set attributes associated with the open message queue 26301 description referenced by the message queue descriptor specified by mqdes. 26302 The message queue attributes corresponding to the following members defined in the mq_attr 26303 structure are set to the specified values upon successful completion of mq_setattr( ): 26304 mq_flags The value of this member is the bitwise-logical OR of zero or more of | 26305 O_NONBLOCK and any implementation-defined flags. | 26306 The values of the mq_maxmsg, mq_msgsize, and mq_curmsgs members of the mq_attr structure are 26307 ignored by mq_setattr( ). 26308 If omqstat is non-NULL, the mq_setattr( ) function stores, in the location referenced by omqstat, the 26309 previous message queue attributes and the current queue status. These values are the same as 26310 would be returned by a call to mq_getattr( ) at that point. 26311 RETURN VALUE 26312 Upon successful completion, the function shall return a value of zero and the attributes of the 26313 message queue shall have been changed as specified. 26314 Otherwise, the message queue attributes shall be unchanged, and the function shall return a 26315 value of -1 and set errno to indicate the error. 26316 ERRORS 26317 The mq_setattr( ) function shall fail if: 26318 [EBADF] The mqdes argument is not a valid message queue descriptor. | 26319 EXAMPLES 26320 None. 26321 APPLICATION USAGE 26322 None. 26323 RATIONALE 26324 None. 26325 FUTURE DIRECTIONS 26326 None. 26327 SEE ALSO 26328 mq_open( ), mq_send( ), mq_timedsend( ), msgctl( ), msgget( ), msgrcv( ), msgsnd( ), the Base | 26329 Definitions volume of IEEE Std. 1003.1-200x, | 26330 CHANGE HISTORY 26331 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. System Interfaces, Issue 6 1311 mq_setattr( ) System Interfaces 26332 Issue 6 26333 The mq_setattr( ) function is marked as part of the Message Passing option. | 26334 The [ENOSYS] error condition has been removed as stubs need not be provided if an 26335 implementation does not support the Message Passing option. | 26336 The mq_timedsend( ) function is added to the SEE ALSO section for alignment with 26337 IEEE Std. 1003.1d-1999. | 26338 The restrict keyword is added to the mq_setattr( ) prototype for alignment with the | 26339 ISO/IEC 9899: 1999 standard. | 1312 Technical Standard (2000) (Draft July 31, 2000) System Interfaces mq_timedreceive( ) 26340 NAME 26341 mq_timedreceive - receive a message from a message queue (REALTIME) 26342 SYNOPSIS 26343 MSG TMO #include 26344 #include 26345 int mq_timedreceive(mqd_t mqdes, char *restrict msg_ptr, | 26346 size_t msg_len, unsigned *restrict msg_prio, | 26347 const struct timespec *restrict abs_timeout); | 26348 | 26349 DESCRIPTION 26350 Refer to mq_receive( ). System Interfaces, Issue 6 1313 mq_timedsend( ) System Interfaces 26351 NAME 26352 mq_timedsend - send a message to a message queue (REALTIME) 26353 SYNOPSIS 26354 MSG TMO #include 26355 #include 26356 int mq_timedsend(mqd_t mqdes, const char *msg_ptr, size_t msg_len, 26357 unsigned msg_prio, const struct timespec *abs_timeout); | 26358 | 26359 DESCRIPTION 26360 Refer to mq_send( ). 1314 Technical Standard (2000) (Draft July 31, 2000) System Interfaces mq_unlink( ) 26361 NAME 26362 mq_unlink - remove a message queue (REALTIME) 26363 SYNOPSIS 26364 MSG #include 26365 int mq_unlink(const char *name); 26366 26367 DESCRIPTION 26368 The mq_unlink( ) function shall remove the message queue named by the path name name. After 26369 a successful call to mq_unlink( ) with name, a call to mq_open( ) with name fails if the flag 26370 O_CREAT is not set in flags. If one or more processes have the message queue open when 26371 mq_unlink( ) is called, destruction of the message queue is postponed until all references to the | 26372 message queue have been closed. | 26373 Calls to mq_open( ) to recreate the message queue may fail until the message queue is actually | 26374 removed. However, the mq_unlink( ) call need not block until all references have been closed; it 26375 may return immediately. 26376 RETURN VALUE 26377 Upon successful completion, the function shall return a value of zero. Otherwise, the named 26378 message queue shall be unchanged by this function call, and the function shall return a value of 26379 -1 and set errno to indicate the error. 26380 ERRORS 26381 The mq_unlink( ) function shall fail if: 26382 [EACCES] Permission is denied to unlink the named message queue. | 26383 [ENAMETOOLONG] | 26384 The length of the name argument exceeds {PATH_MAX} or a path name | 26385 component is longer than {NAME_MAX}. | 26386 [ENOENT] The named message queue does not exist. | 26387 EXAMPLES 26388 None. 26389 APPLICATION USAGE 26390 None. 26391 RATIONALE 26392 None. 26393 FUTURE DIRECTIONS 26394 None. 26395 SEE ALSO 26396 mq_close( ), mq_open( ), msgctl( ), msgget( ), msgrcv( ), msgsnd( ), the Base Definitions volume of | 26397 IEEE Std. 1003.1-200x, | 26398 CHANGE HISTORY 26399 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 26400 Issue 6 26401 The mq_unlink( ) function is marked as part of the Message Passing option. | 26402 The Open Group corrigenda item U021/5 has been applied, clarifying that upon unsuccessful 26403 completion, the named message queue is unchanged by this function. System Interfaces, Issue 6 1315 mq_unlink( ) System Interfaces 26404 The [ENOSYS] error condition has been removed as stubs need not be provided if an 26405 implementation does not support the Message Passing option. | 1316 Technical Standard (2000) (Draft July 31, 2000) System Interfaces mrand48( ) 26406 NAME 26407 mrand48 - generate uniformly distributed pseudo-random signed long integers 26408 SYNOPSIS 26409 XSI #include 26410 long mrand48(void); | 26411 | 26412 DESCRIPTION 26413 Refer to drand48( ). System Interfaces, Issue 6 1317 msgctl( ) System Interfaces 26414 NAME 26415 msgctl - XSI message control operations 26416 SYNOPSIS 26417 XSI #include 26418 int msgctl(int msqid, int cmd, struct msqid_ds *buf); 26419 26420 DESCRIPTION 26421 The msgctl( ) function operates on XSI message queues (see the Base Definitions volume of | 26422 IEEE Std. 1003.1-200x, Section 3.226, Message Queue). It is unspecified whether this function | 26423 interoperates with the realtime interprocess communication facilities defined in Section 2.8 (on 26424 page 543). 26425 The msgctl( ) function shall provide message control operations as specified by cmd. The 26426 following values for cmd, and the message control operations they specify, are: 26427 IPC_STAT Place the current value of each member of the msqid_ds data structure 26428 associated with msqid into the structure pointed to by buf. The contents of this 26429 structure are defined in . 26430 IPC_SET Set the value of the following members of the msqid_ds data structure 26431 associated with msqid to the corresponding value found in the structure 26432 pointed to by buf: 26433 msg_perm.uid 26434 msg_perm.gid 26435 msg_perm.mode 26436 msg_qbytes 26437 IPC_SET can only be executed by a process with appropriate privileges or that 26438 has an effective user ID equal to the value of msg_perm.cuid or 26439 msg_perm.uid in the msqid_ds data structure associated with msqid. Only a 26440 process with appropriate privileges can raise the value of msg_qbytes. 26441 IPC_RMID Remove the message queue identifier specified by msqid from the system and 26442 destroy the message queue and msqid_ds data structure associated with it. 26443 IPC_RMD can only be executed by a process with appropriate privileges or 26444 one that has an effective user ID equal to the value of msg_perm.cuid or 26445 msg_perm.uid in the msqid_ds data structure associated with msqid. 26446 RETURN VALUE 26447 Upon successful completion, msgctl( ) shall return 0; otherwise, it shall return -1 and set errno to 26448 indicate the error. 26449 ERRORS 26450 The msgctl( ) function shall fail if: 26451 [EACCES] The argument cmd is IPC_STAT and the calling process does not have read | 26452 permission; see Section 2.7 (on page 541). 26453 [EINVAL] The value of msqid is not a valid message queue identifier; or the value of cmd | 26454 is not a valid command. 26455 [EPERM] The argument cmd is IPC_RMID or IPC_SET and the effective user ID of the | 26456 calling process is not equal to that of a process with appropriate privileges 26457 and it is not equal to the value of msg_perm.cuid or msg_perm.uid in the data 26458 structure associated with msqid. 1318 Technical Standard (2000) (Draft July 31, 2000) System Interfaces msgctl( ) 26459 [EPERM] The argument cmd is IPC_SET, an attempt is being made to increase to the | 26460 value of msg_qbytes, and the effective user ID of the calling process does not 26461 have appropriate privileges. 26462 EXAMPLES 26463 None. 26464 APPLICATION USAGE 26465 The POSIX Realtime Extension defines alternative interfaces for interprocess communication 26466 (IPC). Application developers who need to use IPC should design their applications so that 26467 modules using the IPC routines described in Section 2.7 (on page 541) can be easily modified to 26468 use the alternative interfaces. 26469 RATIONALE 26470 None. 26471 FUTURE DIRECTIONS 26472 None. 26473 SEE ALSO 26474 mq_close( ), mq_getattr( ), mq_notify( ), mq_open( ), mq_receive( ), mq_send( ), mq_setattr( ), 26475 mq_unlink( ), msgget( ), msgrcv( ), msgsnd( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 26476 , Section 2.7 (on page 541) 26477 CHANGE HISTORY 26478 First released in Issue 2. Derived from Issue 2 of the SVID. | 26479 Issue 4 26480 The function is no longer marked as OPTIONAL FUNCTIONALITY. 26481 Inclusion of the and headers is removed from the SYNOPSIS section. 26482 A FUTURE DIRECTIONS section is added warning application developers about migration to 26483 IEEE 1003.4 interfaces for interprocess communication. 26484 The [ENOSYS] error is removed from the ERRORS section. 26485 Issue 5 26486 The note about use of POSIX Realtime Extension IPC routines has been moved from FUTURE 26487 DIRECTIONS to a new APPLICATION USAGE section. System Interfaces, Issue 6 1319 msgget( ) System Interfaces 26488 NAME 26489 msgget - get the XSI message queue identifier 26490 SYNOPSIS 26491 XSI #include 26492 int msgget(key_t key, int msgflg); 26493 26494 DESCRIPTION 26495 The msgget( ) function operates on XSI message queues (see the Base Definitions volume of | 26496 IEEE Std. 1003.1-200x, Section 3.226, Message Queue). It is unspecified whether this function | 26497 interoperates with the realtime interprocess communication facilities defined in Section 2.8 (on 26498 page 543). 26499 The msgget( ) function shall return the message queue identifier associated with the argument 26500 key. 26501 A message queue identifier, associated message queue, and data structure (see ), are 26502 created for the argument key if one of the following is true: 26503 * The argument key is equal to IPC_PRIVATE. 26504 * The argument key does not already have a message queue identifier associated with it, and 26505 (msgflg & IPC_CREAT) is non-zero. 26506 Upon creation, the data structure associated with the new message queue identifier is initialized 26507 as follows: 26508 * msg_perm.cuid, msg_perm.uid, msg_perm.cgid, and msg_perm.gid are set equal to the 26509 effective user ID and effective group ID, respectively, of the calling process. 26510 * The low-order 9 bits of msg_perm.mode are set equal to the low-order 9 bits of msgflg. 26511 * msg_qnum, msg_lspid, msg_lrpid, msg_stime, and msg_rtime are set equal to 0. 26512 * msg_ctime is set equal to the current time. 26513 * msg_qbytes is set equal to the system limit. 26514 RETURN VALUE 26515 Upon successful completion, msgget( ) shall return a non-negative integer, namely a message 26516 queue identifier. Otherwise, it shall return -1 and set errno to indicate the error. 26517 ERRORS 26518 The msgget( ) function shall fail if: 26519 [EACCES] A message queue identifier exists for the argument key, but operation | 26520 permission as specified by the low-order 9 bits of msgflg would not be granted; 26521 see Section 2.7 (on page 541). 26522 [EEXIST] A message queue identifier exists for the argument key but ((msgflg & | 26523 IPC_CREAT) && (msgflg & IPC_EXCL)) is non-zero. 26524 [ENOENT] A message queue identifier does not exist for the argument key and (msgflg & | 26525 IPC_CREAT) is 0. 26526 [ENOSPC] A message queue identifier is to be created but the system-imposed limit on | 26527 the maximum number of allowed message queue identifiers system-wide 26528 would be exceeded. 1320 Technical Standard (2000) (Draft July 31, 2000) System Interfaces msgget( ) 26529 EXAMPLES 26530 None. 26531 APPLICATION USAGE 26532 The POSIX Realtime Extension defines alternative interfaces for interprocess communication 26533 (IPC). Application developers who need to use IPC should design their applications so that 26534 modules using the IPC routines described in Section 2.7 (on page 541) can be easily modified to 26535 use the alternative interfaces. 26536 RATIONALE 26537 None. 26538 FUTURE DIRECTIONS 26539 None. 26540 SEE ALSO 26541 mq_close( ), mq_getattr( ), mq_notify( ), mq_open( ), mq_receive( ), mq_send( ), mq_setattr( ), 26542 mq_unlink( ), msgctl( ), msgrcv( ), msgsnd( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 26543 , Section 2.7 (on page 541) 26544 CHANGE HISTORY 26545 First released in Issue 2. Derived from Issue 2 of the SVID. | 26546 Issue 4 26547 The function is no longer marked as OPTIONAL FUNCTIONALITY. 26548 Inclusion of the and headers is removed from the SYNOPSIS section. 26549 The [ENOSYS] error is removed from the ERRORS section. 26550 Issue 5 26551 The note about use of POSIX Realtime Extension IPC routines has been moved from FUTURE 26552 DIRECTIONS to a new APPLICATION USAGE section. System Interfaces, Issue 6 1321 msgrcv( ) System Interfaces 26553 NAME 26554 msgrcv - XSI message receive operation 26555 SYNOPSIS 26556 XSI #include 26557 ssize_t msgrcv(int msqid, void *msgp, size_t msgsz, long msgtyp, | 26558 int msgflg); | 26559 26560 DESCRIPTION 26561 The msgrcv( ) function operates on XSI message queues (see the Base Definitions volume of | 26562 IEEE Std. 1003.1-200x, Section 3.226, Message Queue). It is unspecified whether this function | 26563 interoperates with the realtime interprocess communication facilities defined in Section 2.8 (on 26564 page 543). 26565 The msgrcv( ) function shall read a message from the queue associated with the message queue 26566 identifier specified by msqid and place it in the user-defined buffer pointed to by msgp. 26567 The application shall ensure that the argument msgp points to a user-defined buffer that contains 26568 first a field of type long specifying the type of the message, and then a data portion that holds | 26569 the data bytes of the message. The structure below is an example of what this user-defined 26570 buffer might look like: 26571 struct mymsg { 26572 long mtype; /* Message type. */ 26573 char mtext[1]; /* Message text. */ 26574 } 26575 The structure member mtype is the received message's type as specified by the sending process. 26576 The structure member mtext is the text of the message. 26577 The argument msgsz specifies the size in bytes of mtext. The received message is truncated to 26578 msgsz bytes if it is larger than msgsz and (msgflg & MSG_NOERROR) is non-zero. The truncated 26579 part of the message is lost and no indication of the truncation is given to the calling process. 26580 If the value of msgsz is greater than {SSIZE_MAX}, the result is implementation-defined. | 26581 The argument msgtyp specifies the type of message requested as follows: 26582 * If msgtyp is 0, the first message on the queue is received. 26583 * If msgtyp is greater than 0, the first message of type msgtyp is received. 26584 * If msgtyp is less than 0, the first message of the lowest type that is less than or equal to the 26585 absolute value of msgtyp is received. 26586 The argument msgflg specifies the action to be taken if a message of the desired type is not on the 26587 queue. These are as follows: 26588 * If (msgflg & IPC_NOWAIT) is non-zero, the calling thread shall return immediately with a 26589 return value of -1 and errno set to [ENOMSG]. 26590 * If (msgflg & IPC_NOWAIT) is 0, the calling thread shall suspend execution until one of the 26591 following occurs: 26592 - A message of the desired type is placed on the queue. 26593 - The message queue identifier msqid is removed from the system; when this occurs, errno 26594 shall be set equal to [EIDRM] and -1 shall be returned. 1322 Technical Standard (2000) (Draft July 31, 2000) System Interfaces msgrcv( ) 26595 - The calling thread receives a signal that is to be caught; in this case a message is not 26596 received and the calling thread resumes execution in the manner prescribed in sigaction( ). 26597 Upon successful completion, the following actions are taken with respect to the data structure 26598 associated with msqid: 26599 * msg_qnum is decremented by 1. 26600 * msg_lrpid is set equal to the process ID of the calling process. 26601 * msg_rtime is set equal to the current time. 26602 RETURN VALUE 26603 Upon successful completion, msgrcv( ) shall return a value equal to the number of bytes actually 26604 placed into the buffer mtext. Otherwise, no message shall be received, msgrcv( ) shall return 26605 (ssize_t)-1, and errno shall be set to indicate the error. 26606 ERRORS 26607 The msgrcv( ) function shall fail if: 26608 [E2BIG] The value of mtext is greater than msgsz and (msgflg & MSG_NOERROR) is 0. | 26609 [EACCES] Operation permission is denied to the calling process; see Section 2.7 (on page | 26610 541). 26611 [EIDRM] The message queue identifier msqid is removed from the system. | 26612 [EINTR] The msgrcv( ) function was interrupted by a signal. | 26613 [EINVAL] msqid is not a valid message queue identifier. | 26614 [ENOMSG] The queue does not contain a message of the desired type and (msgflg & | 26615 IPC_NOWAIT) is non-zero. 26616 EXAMPLES 26617 Receiving a Message 26618 The following example receives the first message on the queue (based on the value of the 26619 msgtype argument, 0). The queue is identified by the msqid argument (assuming that the value 26620 has previously been set). This call specifies that an error should be reported if no message is 26621 available, but not if the message is too large. The message size is calculated directly using the 26622 sizeof operator. 26623 #include 26624 ... 26625 int result; 26626 int msqid; 26627 struct message { 26628 long type; 26629 char text[20]; 26630 } msg; 26631 long msgtyp = 0; 26632 ... 26633 result = msgrcv(msqid, (void *) &msg, sizeof(msg.text), 26634 msgtyp, MSG_NOERROR | IPC_NOWAIT); System Interfaces, Issue 6 1323 msgrcv( ) System Interfaces 26635 APPLICATION USAGE 26636 The POSIX Realtime Extension defines alternative interfaces for interprocess communication 26637 (IPC). Application developers who need to use IPC should design their applications so that 26638 modules using the IPC routines described in Section 2.7 (on page 541) can be easily modified to 26639 use the alternative interfaces. 26640 RATIONALE 26641 None. 26642 FUTURE DIRECTIONS 26643 None. 26644 SEE ALSO 26645 mq_close( ), mq_getattr( ), mq_notify( ), mq_open( ), mq_receive( ), mq_send( ), mq_setattr( ), 26646 mq_unlink( ), msgctl( ), msgget( ), msgsnd( ), sigaction( ), the Base Definitions volume of | 26647 IEEE Std. 1003.1-200x, , Section 2.7 (on page 541) | 26648 CHANGE HISTORY 26649 First released in Issue 2. Derived from Issue 2 of the SVID. | 26650 Issue 4 26651 The function is no longer marked as OPTIONAL FUNCTIONALITY. 26652 Inclusion of the and headers is removed from the SYNOPSIS section. 26653 The [ENOSYS] error is removed from the ERRORS section. 26654 A FUTURE DIRECTIONS section is added warning application developers about migration to 26655 IEEE 1003.4 interfaces for interprocess communication. 26656 Issue 5 26657 The type of the return value is changed from int to ssize_t, and a warning is added to the 26658 DESCRIPTION about values of msgsz larger the {SSIZE_MAX}. 26659 The note about use of POSIX Realtime Extension IPC routines has been moved from FUTURE 26660 DIRECTIONS to the APPLICATION USAGE section. 26661 Issue 6 26662 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 1324 Technical Standard (2000) (Draft July 31, 2000) System Interfaces msgsnd( ) 26663 NAME 26664 msgsnd - XSI message send operation 26665 SYNOPSIS 26666 XSI #include 26667 int msgsnd(int msqid, const void *msgp, size_t msgsz, int msgflg); 26668 26669 DESCRIPTION 26670 The msgsnd( ) function operates on XSI message queues (see the Base Definitions volume of | 26671 IEEE Std. 1003.1-200x, Section 3.226, Message Queue). It is unspecified whether this function | 26672 interoperates with the realtime interprocess communication facilities defined in Section 2.8 (on 26673 page 543). 26674 The msgsnd( ) function is used to send a message to the queue associated with the message 26675 queue identifier specified by msqid. 26676 The application shall ensure that the argument msgp points to a user-defined buffer that contains 26677 first a field of type long specifying the type of the message, and then a data portion that holds | 26678 the data bytes of the message. The structure below is an example of what this user-defined 26679 buffer might look like: 26680 struct mymsg { 26681 long mtype; /* Message type. */ 26682 char mtext[1]; /* Message text. */ 26683 } 26684 The structure member mtype is a non-zero positive type long that can be used by the receiving | 26685 process for message selection. 26686 The structure member mtext is any text of length msgsz bytes. The argument msgsz can range 26687 from 0 to a system-imposed maximum. 26688 The argument msgflg specifies the action to be taken if one or more of the following are true: 26689 * The number of bytes already on the queue is equal to msg_qbytes; see . 26690 * The total number of messages on all queues system-wide is equal to the system-imposed 26691 limit. 26692 These actions are as follows: 26693 * If (msgflg & IPC_NOWAIT) is non-zero, the message shall not be sent and the calling thread 26694 shall return immediately. 26695 * If (msgflg & IPC_NOWAIT) is 0, the calling thread shall suspend execution until one of the 26696 following occurs: 26697 - The condition responsible for the suspension no longer exists, in which case the message 26698 is sent. 26699 - The message queue identifier msqid is removed from the system; when this occurs, errno 26700 shall be set equal to [EIDRM] and -1 shall be returned. 26701 - The calling thread receives a signal that is to be caught; in this case the message is not 26702 sent and the calling thread resumes execution in the manner prescribed in sigaction( ). 26703 Upon successful completion, the following actions are taken with respect to the data structure 26704 associated with msqid; see : System Interfaces, Issue 6 1325 msgsnd( ) System Interfaces 26705 * msg_qnum is incremented by 1. 26706 * msg_lspid is set equal to the process ID of the calling process. 26707 * msg_stime is set equal to the current time. 26708 RETURN VALUE 26709 Upon successful completion, msgsnd( ) shall return 0; otherwise, no message shall be sent, 26710 msgsnd( ) shall return -1, and errno shall be set to indicate the error. 26711 ERRORS 26712 The msgsnd( ) function shall fail if: 26713 [EACCES] Operation permission is denied to the calling process; see Section 2.7 (on page | 26714 541). 26715 [EAGAIN] The message cannot be sent for one of the reasons cited above and (msgflg & | 26716 IPC_NOWAIT) is non-zero. 26717 [EIDRM] The message queue identifier msgid is removed from the system. | 26718 [EINTR] The msgsnd( ) function was interrupted by a signal. | 26719 [EINVAL] The value of msqid is not a valid message queue identifier, or the value of | 26720 mtype is less than 1; or the value of msgsz is less than 0 or greater than the 26721 system-imposed limit. 26722 EXAMPLES 26723 Sending a Message 26724 The following example sends a message to the queue identified by the msqid argument 26725 (assuming that value has previously been set). This call specifies that an error should be 26726 reported if no message is available. The message size is calculated directly using the sizeof 26727 operator. 26728 #include 26729 ... 26730 int result; 26731 int msqid; 26732 struct message { 26733 long type; 26734 char text[20]; 26735 } msg; 26736 msg.type = 1; 26737 strcpy(msg.text, "This is message 1"); 26738 ... 26739 result = msgsnd(msqid, (void *) &msg, sizeof(msg.text), IPC_NOWAIT); 26740 APPLICATION USAGE 26741 The POSIX Realtime Extension defines alternative interfaces for interprocess communication 26742 (IPC). Application developers who need to use IPC should design their applications so that 26743 modules using the IPC routines described in Section 2.7 (on page 541) can be easily modified to 26744 use the alternative interfaces. 1326 Technical Standard (2000) (Draft July 31, 2000) System Interfaces msgsnd( ) 26745 RATIONALE 26746 None. 26747 FUTURE DIRECTIONS 26748 None. 26749 SEE ALSO 26750 mq_close( ), mq_getattr( ), mq_notify( ), mq_open( ), mq_receive( ), mq_send( ), mq_setattr( ), 26751 mq_unlink( ), msgctl( ), msgget( ), msgrcv( ), sigaction( ), the Base Definitions volume of | 26752 IEEE Std. 1003.1-200x, , Section 2.7 (on page 541) | 26753 CHANGE HISTORY 26754 First released in Issue 2. Derived from Issue 2 of the SVID. | 26755 Issue 4 26756 The function is no longer marked as OPTIONAL FUNCTIONALITY. 26757 Inclusion of the and headers is removed from the SYNOPSIS section. 26758 Also the type of argument msgp is changed from void* to const void*. 26759 In the DESCRIPTION, the example of a message buffer is changed: 26760 * Explicitly to define the first member as being of type long | 26761 * To define the size of the message array mtext 26762 The [ENOSYS] error is removed from the ERRORS section. 26763 A FUTURE DIRECTIONS section is added warning application developers about migration to 26764 IEEE 1003.4 interfaces for interprocess communication. 26765 Issue 5 26766 The note about use of POSIX Realtime Extension IPC routines has been moved from FUTURE 26767 DIRECTIONS to a new APPLICATION USAGE section. 26768 Issue 6 26769 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1327 msync( ) System Interfaces 26770 NAME 26771 msync - synchronize memory with physical storage 26772 SYNOPSIS 26773 MF SIO #include 26774 int msync(void *addr, size_t len, int flags); 26775 26776 DESCRIPTION 26777 The msync( ) function shall write all modified data to permanent storage locations, if any, in 26778 those whole pages containing any part of the address space of the process starting at address 26779 addr and continuing for len bytes. If no such storage exists, msync( ) need not have any effect. If 26780 requested, the msync( ) function then invalidates cached copies of data. 26781 The implementation shall require that addr be a multiple of the page size as returned by | 26782 sysconf( ). 26783 For mappings to files, the msync( ) function ensures that all write operations are completed as 26784 defined for synchronized I/O data integrity completion. It is unspecified whether the 26785 implementation also writes out other file attributes. When the msync( ) function is called on 26786 MAP_PRIVATE mappings, any modified data shall not be written to the underlying object and 26787 shall not cause such data to be made visible to other processes. It is unspecified whether data in 26788 SHM|TYM MAP_PRIVATE mappings has any permanent storage locations. The effect of msync( ) on a 26789 shared memory object or a typed memory object is unspecified. The behavior of this function is | 26790 unspecified if the mapping was not established by a call to mmap( ). | 26791 The flags argument is constructed from the bitwise-inclusive OR of one or more of the following 26792 flags defined in the header : 26793 _________________________________________________ 26794 _ Symbolic Constant Description ________________________________________________ 26795 MS_ASYNC Perform asynchronous writes. 26796 MS_SYNC Perform synchronous writes. 26797 _ MS_INVALIDATE Invalidate cached data. ________________________________________________ 26798 When MS_ASYNC is specified, msync( ) shall return immediately once all the write operations 26799 are initiated or queued for servicing; when MS_SYNC is specified, msync( ) shall not return until 26800 all write operations are completed as defined for synchronized I/O data integrity completion. 26801 Either MS_ASYNC or MS_SYNC is specified, but not both. 26802 When MS_INVALIDATE is specified, msync( ) invalidates all cached copies of mapped data that 26803 are inconsistent with the permanent storage locations such that subsequent references shall 26804 obtain data that was consistent with the permanent storage locations sometime between the call 26805 to msync( ) and the first subsequent memory reference to the data. 26806 If msync( ) causes any write to a file, the file's st_ctime and st_mtime fields shall be marked for | 26807 update. 26808 RETURN VALUE 26809 Upon successful completion, msync( ) shall return 0; otherwise, it shall return -1 and set errno to 26810 indicate the error. 26811 ERRORS 26812 The msync( ) function shall fail if: 26813 [EBUSY] Some or all of the addresses in the range starting at addr and continuing for len | 26814 bytes are locked, and MS_INVALIDATE is specified. | 1328 Technical Standard (2000) (Draft July 31, 2000) System Interfaces msync( ) 26815 [EINVAL] The value of flags is invalid. | 26816 [EINVAL] The value of addr is not a multiple of the page size, {PAGESIZE}. | 26817 [ENOMEM] The addresses in the range starting at addr and continuing for len bytes are | 26818 outside the range allowed for the address space of a process or specify one or 26819 more pages that are not mapped. 26820 EXAMPLES 26821 None. 26822 APPLICATION USAGE 26823 The msync( ) function is only supported if the Memory Mapped Files option and the | 26824 Synchronized Input and Output option are supported, and thus need not be available on all | 26825 implementations. 26826 The msync( ) function should be used by programs that require a memory object to be in a 26827 known state; for example, in building transaction facilities. 26828 Normal system activity can cause pages to be written to disk. Therefore, there are no guarantees 26829 that msync( ) is the only control over when pages are or are not written to disk. 26830 RATIONALE 26831 The msync( ) function is used to write out data in a mapped region to the permanent storage for 26832 the underlying object. The call to msync( ) ensures data integrity of the file. 26833 After the data is written out, any cached data may be invalidated if the MS_INVALIDATE flag 26834 was specified. This is useful on systems that do not support read/write consistency. 26835 FUTURE DIRECTIONS 26836 None. 26837 SEE ALSO 26838 mmap( ), sysconf( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 26839 CHANGE HISTORY 26840 First released in Issue 4, Version 2. 26841 Issue 5 26842 Moved from X/OPEN UNIX extension to BASE. 26843 Aligned with msync( ) in the POSIX Realtime Extension as follows: 26844 * The DESCRIPTION is extensively reworded. 26845 * [EBUSY] and a new form of [EINVAL] are added as mandatory error conditions. 26846 Issue 6 26847 The msync( ) function is marked as part of the Memory Mapped Files and Synchronized Input | 26848 and Output options. | 26849 The following changes are made for alignment with the ISO POSIX-1: 1996 standard: 26850 * The [EBUSY] mandatory error condition is added. 26851 The following new requirements on POSIX implementations derive from alignment with the 26852 Single UNIX Specification: 26853 * The DESCRIPTION is updated to state that implementations require addr to be a multiple of 26854 the page size. 26855 * The second [EINVAL] error condition is made mandatory. System Interfaces, Issue 6 1329 msync( ) System Interfaces 26856 The DESCRIPTION is updated for alignment with IEEE Std. 1003.1j-2000 by adding reference to 26857 typed memory objects. 1330 Technical Standard (2000) (Draft July 31, 2000) System Interfaces munlock( ) 26858 NAME 26859 munlock - unlock a range of process address space 26860 SYNOPSIS 26861 MLR #include 26862 int munlock(const void * addr, size_t len); 26863 26864 DESCRIPTION 26865 Refer to mlock( ). System Interfaces, Issue 6 1331 munlockall( ) System Interfaces 26866 NAME 26867 munlockall - unlock the address space of a process 26868 SYNOPSIS 26869 ML #include 26870 int munlockall(void); 26871 26872 DESCRIPTION 26873 Refer to mlockall( ). 1332 Technical Standard (2000) (Draft July 31, 2000) System Interfaces munmap( ) 26874 NAME 26875 munmap - unmap pages of memory 26876 SYNOPSIS 26877 MF|SHM #include 26878 int munmap(void *addr, size_t len); 26879 26880 DESCRIPTION 26881 The munmap( ) function shall remove any mappings for those entire pages containing any part of 26882 the address space of the process starting at addr and continuing for len bytes. Further references 26883 to these pages result in the generation of a SIGSEGV signal to the process. If there are no 26884 mappings in the specified address range, then munmap( ) has no effect. 26885 The implementation shall require that addr be a multiple of the page size {PAGESIZE}. | 26886 If a mapping to be removed was private, any modifications made in this address range shall be 26887 discarded. 26888 ML|MLR Any memory locks (see mlock( ) and mlockall ( )) associated with this address range shall be 26889 removed, as if by an appropriate call to munlock( ). 26890 TYM If a mapping removed from a typed memory object causes the corresponding address range of 26891 the memory pool to be inaccessible by any process in the system except through allocatable 26892 mappings (that is, mappings of typed memory objects opened with the 26893 POSIX_TYPED_MEM_MAP_ALLOCATABLE flag), then that range of the memory pool shall 26894 become deallocated and may become available to satisfy future typed memory allocation 26895 requests. 26896 A mapping removed from a typed memory object opened with the 26897 POSIX_TYPED_MEM_MAP_ALLOCATABLE flag shall not affect in any way the availability of 26898 that typed memory for allocation. 26899 The behavior of this function is unspecified if the mapping was not established by a call to 26900 mmap( ). 26901 RETURN VALUE 26902 Upon successful completion, munmap( ) shall return 0; otherwise, it shall return -1 and set errno 26903 to indicate the error. 26904 ERRORS 26905 The munmap( ) function shall fail if: 26906 [EINVAL] Addresses in the range [addr,addr+len) are outside the valid range for the | 26907 address space of a process. | 26908 [EINVAL] The len argument is 0. | 26909 [EINVAL] The addr argument is not a multiple of the page size as returned by sysconf( ). | System Interfaces, Issue 6 1333 munmap( ) System Interfaces 26910 EXAMPLES 26911 None. 26912 APPLICATION USAGE 26913 The munmap( ) function is only supported if the Memory Mapped Files option or the Shared | 26914 Memory Objects option is supported. | 26915 RATIONALE 26916 The munmap( ) function corresponds to SVR4, just as the mmap( ) function does. 26917 It is possible that an application has applied process memory locking to a region that contains 26918 shared memory. If this has occurred, the munmap( ) call ignores those locks and, if necessary, 26919 causes those locks to be removed. 26920 FUTURE DIRECTIONS 26921 None. 26922 SEE ALSO 26923 mlock( ), mlockall( ), mmap( ), posix_typed_mem_open( ), sysconf( ), the Base Definitions volume of | 26924 IEEE Std. 1003.1-200x, , | 26925 CHANGE HISTORY 26926 First released in Issue 4, Version 2. 26927 Issue 5 26928 Moved from X/OPEN UNIX extension to BASE. 26929 Aligned with munmap( ) in the POSIX Realtime Extension as follows: 26930 * The DESCRIPTION is extensively reworded. 26931 * The SIGBUS error is no longer permitted to be generated. 26932 Issue 6 26933 The munmap( ) function is marked as part of the Memory Mapped Files and Shared Memory | 26934 Objects option. | 26935 The following new requirements on POSIX implementations derive from alignment with the 26936 Single UNIX Specification: 26937 * The DESCRIPTION is updated to state that implementations require addr to be a multiple of 26938 the page size. 26939 * The [EINVAL] error conditions are added. 26940 The following changes are made for alignment with IEEE Std. 1003.1j-2000: 26941 * Semantics for typed memory objects are added to the DESCRIPTION. | 26942 * The posix_typed_mem_open( ) function is added to the SEE ALSO section. 1334 Technical Standard (2000) (Draft July 31, 2000) System Interfaces nan( ) 26943 NAME | 26944 nan, nanf, nanl - return quiet NaN | 26945 SYNOPSIS | 26946 #include | 26947 double nan(const char *tagp); | 26948 float nanf(const char *tagp); | 26949 long double nanl(const char *tagp); | 26950 DESCRIPTION | 26951 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 26952 conflict between the requirements described here and the ISO C standard is unintentional. This | 26953 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 26954 The function call nan("n-char-sequence") shall be equivalent to: | 26955 strtod("NAN(n-char-sequence)", (char **) NULL); | 26956 The function call nan(" ") shall be equivalent to: | 26957 strtod("NAN()", (char **) NULL) | 26958 If tagp does not point to an n-char sequence or an empty string, the function call shall be | 26959 equivalent to: | 26960 strtod("NAN", (char **) NULL) | 26961 Function calls to nanf( ) and nanl( ) are equivalent to the corresponding function calls to strtof( ) | 26962 and strtold( ). | 26963 RETURN VALUE | 26964 These functions shall return a quiet NaN, if available, with content indicated through tagp. | 26965 If the implementation does not support quiet NaNs, these functions shall return zero. | 26966 ERRORS | 26967 No errors are defined. | 26968 EXAMPLES | 26969 None. | 26970 APPLICATION USAGE | 26971 None. | 26972 RATIONALE | 26973 None. | 26974 FUTURE DIRECTIONS | 26975 None. | 26976 SEE ALSO | 26977 strtod( ), (strtold), the Base Definitions volume of | 26978 IEEE Std. 1003.1-200x, | 26979 CHANGE HISTORY || 26980 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | System Interfaces, Issue 6 1335 nanosleep( ) System Interfaces 26981 NAME 26982 nanosleep - high resolution sleep (REALTIME) 26983 SYNOPSIS 26984 TMR #include 26985 int nanosleep(const struct timespec *rqtp, struct timespec *rmtp); 26986 26987 DESCRIPTION 26988 The nanosleep( ) function shall cause the current thread to be suspended from execution until 26989 either the time interval specified by the rqtp argument has elapsed or a signal is delivered to the 26990 calling thread, and its action is to invoke a signal-catching function or to terminate the process. 26991 The suspension time may be longer than requested because the argument value is rounded up to 26992 an integer multiple of the sleep resolution or because of the scheduling of other activity by the 26993 system. But, except for the case of being interrupted by a signal, the suspension time shall not be 26994 less than the time specified by rqtp, as measured by the system clock, CLOCK_REALTIME. 26995 The use of the nanosleep( ) function has no effect on the action or blockage of any signal. 26996 RETURN VALUE 26997 If the nanosleep( ) function returns because the requested time has elapsed, its return value shall 26998 be zero. 26999 If the nanosleep( ) function returns because it has been interrupted by a signal, the function shall 27000 return a value of -1 and set errno to indicate the interruption. If the rmtp argument is non-NULL, 27001 the timespec structure referenced by it is updated to contain the amount of time remaining in 27002 the interval (the requested time minus the time actually slept). If the rmtp argument is NULL, the 27003 remaining time is not returned. 27004 If nanosleep( ) fails, it shall return a value of -1 and set errno to indicate the error. 27005 ERRORS 27006 The nanosleep( ) function shall fail if: 27007 [EINTR] The nanosleep( ) function was interrupted by a signal. | 27008 [EINVAL] The rqtp argument specified a nanosecond value less than zero or greater than | 27009 or equal to 1000 million. 27010 EXAMPLES 27011 None. 27012 APPLICATION USAGE 27013 None. 27014 RATIONALE 27015 It is common to suspend execution of a process for an interval in order to poll the status of a 27016 non-interrupting function. A large number of actual needs can be met with a simple extension to 27017 sleep( ) that provides finer resolution. 27018 In the POSIX.1-1990 standard and SVR4, it is possible to implement such a routine, but the 27019 frequency of wakeup is limited by the resolution of the alarm( ) and sleep( ) functions. In 4.3 BSD, 27020 it is possible to write such a routine using no static storage and reserving no system facilities. 27021 Although it is possible to write a function with similar functionality to sleep( ) using the 27022 remainder of the timers function, such a function requires the use of signals and the reservation 27023 of some signal number. This volume of IEEE Std. 1003.1-200x requires that nanosleep( ) be non- 27024 intrusive of the signals function. 1336 Technical Standard (2000) (Draft July 31, 2000) System Interfaces nanosleep( ) 27025 The nanosleep( ) function shall return a value of 0 on success and -1 on failure or if interrupted. 27026 This latter case is different from sleep( ). This was done because the remaining time is returned 27027 via an argument structure pointer, rmtp, instead of as the return value. 27028 FUTURE DIRECTIONS 27029 None. 27030 SEE ALSO 27031 sleep( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 27032 CHANGE HISTORY 27033 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 27034 Issue 6 27035 The nanosleep( ) function is marked as part of the Timers option. | 27036 The [ENOSYS] error condition has been removed as stubs need not be provided if an | 27037 implementation does not support the Timers option. | System Interfaces, Issue 6 1337 nearbyint( ) System Interfaces 27038 NAME | 27039 nearbyint, nearbyintf, nearbyintl - floating-point rounding functions | 27040 SYNOPSIS | 27041 #include | 27042 double nearbyint(double x); | 27043 float nearbyintf(float x); | 27044 long double nearbyintl(long double x); | 27045 DESCRIPTION | 27046 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 27047 conflict between the requirements described here and the ISO C standard is unintentional. This | 27048 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 27049 These functions shall round their argument to an integer value in floating-point format, using | 27050 the current rounding direction and without raising the inexact floating-point exception. | 27051 An application wishing to check for error situations should set errno to 0 before calling these | 27052 functions. If errno is non-zero on return, or the return value is NaN, an error has occurred. | 27053 RETURN VALUE | 27054 Upon successful completion, these functions shall return the rounded integer value. | 27055 If x is ±Inf, these functions shall return x. | 27056 If x is NaN, NaN shall be returned and errno may be set to [EDOM]. | 27057 ERRORS | 27058 These functions may fail if: | 27059 [EDOM] The value of x is NaN. | 27060 EXAMPLES | 27061 None. | 27062 APPLICATION USAGE | 27063 None. | 27064 RATIONALE | 27065 None. | 27066 FUTURE DIRECTIONS | 27067 None. | 27068 SEE ALSO | 27069 The Base Definitions volume of IEEE Std. 1003.1-200x, | 27070 CHANGE HISTORY || 27071 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | 1338 Technical Standard (2000) (Draft July 31, 2000) System Interfaces nextafter( ) 27072 NAME 27073 nextafter, nextafterf, nextafterl, nexttoward, nexttowardf, nexttowardl - next representable | 27074 double-precision floating-point number 27075 SYNOPSIS 27076 XSI #include 27077 double nextafter(double x, double y); 27078 float nextafterf(float x, float y); | 27079 long double nextafterl(long double x, long double y); | 27080 double nexttoward(double x, long double y); | 27081 float nexttowardf(float x, long double y); | 27082 long double nexttowardl(long double x, long double y); | 27083 | 27084 DESCRIPTION 27085 CX The functionality described on this reference page is aligned with the ISO C standard. Any | 27086 conflict between the requirements described here and the ISO C standard is unintentional. This | 27087 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. | 27088 The nextafter( ), nextafterf( ), and nextafterl( ) functions shall compute the next representable | 27089 double-precision floating-point value following x in the direction of y . Thus, if y is less than x, | 27090 nextafter( ) returns the largest representable floating-point number less than x. The nextafter( ), | 27091 nextafterf( ), and nextafterl( ) functions shall return y if x equals y. | 27092 The nexttoward( ), nexttowardf( ), and nexttowardl( ) functions are equivalent to the corresponding | 27093 nextafter( ) functions, except that the second parameter has type long double and the functions | 27094 return y converted to the type of the function if x equals y. | 27095 An application wishing to check for error situations should set errno to 0 before calling | 27096 nextafter( ). If errno is non-zero on return, or the value NaN is returned, an error has occurred. 27097 RETURN VALUE 27098 These functions shall return the next representable double-precision floating-point value | 27099 following x in the direction of y. The nextafter( ), nextafterf( ), and nextafterl( ) functions shall | 27100 return y if x equals y. | 27101 If x or y is NaN, then nextafter( ) shall return NaN and may set errno to [EDOM]. | 27102 If x is finite and the correct function value would overflow, HUGE_VAL shall be returned and 27103 errno set to [ERANGE]. | 27104 ERRORS 27105 These functions shall fail if: | 27106 [ERANGE] The correct value would overflow. | 27107 These functions may fail if: | 27108 [EDOM] The x or y argument is NaN. | System Interfaces, Issue 6 1339 nextafter( ) System Interfaces 27109 EXAMPLES 27110 None. 27111 APPLICATION USAGE 27112 None. 27113 RATIONALE 27114 None. 27115 FUTURE DIRECTIONS 27116 None. 27117 SEE ALSO 27118 The Base Definitions volume of IEEE Std. 1003.1-200x, | 27119 CHANGE HISTORY 27120 First released in Issue 4, Version 2. 27121 Issue 5 27122 Moved from X/OPEN UNIX extension to BASE. | 27123 Issue 6 | 27124 The nextafterf( ), nextafterl( ), nexttoward( ), nexttowardf( ), nexttowardl( ) functions are added for | 27125 alignment with the ISO/IEC 9899: 1999 standard. | 1340 Technical Standard (2000) (Draft July 31, 2000) System Interfaces nftw( ) 27126 NAME 27127 nftw - walk a file tree 27128 SYNOPSIS 27129 XSI #include 27130 int nftw(const char *path, int (*fn)(const char *, 27131 const struct stat *, int, struct FTW *), int depth, int flags); 27132 27133 DESCRIPTION 27134 The nftw( ) function shall recursively descend the directory hierarchy rooted in path. The nftw( ) 27135 function has a similar effect to ftw( ) except that it takes an additional argument flags, which is a 27136 bitwise-inclusive OR of zero or more of the following flags: 27137 FTW_CHDIR If set, nftw( ) shall change the current working directory to each directory as it 27138 reports files in that directory. If clear, nftw( ) shall not change the current 27139 working directory. 27140 FTW_DEPTH If set, nftw( ) shall report all files in a directory before reporting the directory 27141 itself. If clear, nftw( ) shall report any directory before reporting the files in that 27142 directory. 27143 FTW_MOUNT If set, nftw( ) shall only report files in the same file system as path. If clear, 27144 nftw( ) shall report all files encountered during the walk. 27145 FTW_PHYS If set, nftw( ) shall perform a physical walk and shall not follow symbolic links. 27146 If FTW_PHYS is clear and FTW_DEPTH is set, nftw( ) shall follow links instead of reporting 27147 them, but shall not report any directory that would be a descendant of itself. If FTW_PHYS is 27148 clear and FTW_DEPTH is clear, nftw( ) shall follow links instead of reporting them, but shall not 27149 report the contents of any directory that would be a descendant of itself. 27150 At each file it encounters, nftw( ) shall call the user-supplied function fn with four arguments: 27151 * The first argument is the path name of the object. 27152 * The second argument is a pointer to the stat buffer containing information on the object. 27153 * The third argument is an integer giving additional information. Its value is one of the 27154 following: 27155 FTW_F The object is a file. 27156 FTW_D The object is a directory. 27157 FTW_DP The object is a directory and subdirectories have been visited. (This condition 27158 shall only occur if the FTW_DEPTH flag is included in flags.) 27159 FTW_SL The object is a symbolic link. (This condition shall only occur if the FTW_PHYS 27160 flag is included in flags.) 27161 FTW_SLN The object is a symbolic link that does not name an existing file. (This 27162 condition shall only occur if the FTW_PHYS flag is not included in flags.) 27163 FTW_DNR The object is a directory that cannot be read. The fn function shall not be called 27164 for any of its descendants. 27165 FTW_NS The stat( ) function failed on the object because of lack of appropriate 27166 permission. The stat buffer passed to fn is undefined. Failure of stat( ) for any 27167 other reason is considered an error and nftw( ) shall return -1. System Interfaces, Issue 6 1341 nftw( ) System Interfaces 27168 * The fourth argument is a pointer to an FTW structure. The value of base is the offset of the 27169 object's file name in the path name passed as the first argument to fn. The value of level 27170 indicates depth relative to the root of the walk, where the root level is 0. 27171 The argument depth sets the maximum number of file descriptors that are shall be by nftw( ) 27172 while traversing the file tree. At most one file descriptor shall be used for each directory level. 27173 RETURN VALUE 27174 The nftw( ) function shall continue until the first of the following conditions occurs: 27175 * An invocation of fn shall return a non-zero value, in which case nftw( ) shall return that value. 27176 * The nftw( ) function detects an error other than [EACCES] (see FTW_DNR and FTW_NS | 27177 above), in which case nftw( ) shall return -1 and set errno to indicate the error. 27178 * The tree is exhausted, in which case nftw( ) shall return 0. 27179 ERRORS 27180 The nftw( ) function shall fail if: 27181 [EACCES] Search permission is denied for any component of path or read permission is | 27182 denied for path, or fn returns -1 and does not reset errno. | 27183 [ELOOP] A loop exists in symbolic links encountered during resolution of the path | 27184 argument. | 27185 [ENAMETOOLONG] | 27186 The length of the path argument exceeds {PATH_MAX} or a path name | 27187 component is longer than {NAME_MAX}. 27188 [ENOENT] A component of path does not name an existing file or path is an empty string. | 27189 [ENOTDIR] A component of path is not a directory. | 27190 The nftw( ) function may fail if: 27191 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during | 27192 resolution of the path argument. | 27193 [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. | 27194 [ENAMETOOLONG] | 27195 Path name resolution of a symbolic link produced an intermediate result 27196 whose length exceeds {PATH_MAX}. 27197 [ENFILE] Too many files are currently open in the system. | 27198 In addition, errno may be set if the function pointed by fn causes errno to be set. 27199 EXAMPLES 27200 The following example walks the /tmp directory and its subdirectories, calling the nftw( ) 27201 function for every directory entry, to a maximum of 5 levels deep. 27202 #include 27203 ... 27204 int nftwfunc(const char *, const struct stat *, int, struct FTW *); 27205 int nftwfunc(const char *filename, const struct stat *statptr, 27206 int fileflags, struct FTW *pfwt) 27207 { 27208 return 0; 27209 } 1342 Technical Standard (2000) (Draft July 31, 2000) System Interfaces nftw( ) 27210 ... 27211 char *startpath = "/tmp"; 27212 int depth = 5; 27213 int flags = FTW_CHDIR | FTW_DEPTH | FTW_MOUNT; 27214 int ret; 27215 ret = nftw(startpath, nftwfunc, depth, flags); 27216 APPLICATION USAGE 27217 None. 27218 RATIONALE 27219 None. 27220 FUTURE DIRECTIONS 27221 None. 27222 SEE ALSO 27223 lstat( ), opendir( ), readdir( ), stat( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 27224 CHANGE HISTORY 27225 First released in Issue 4, Version 2. 27226 Issue 5 27227 Moved from X/OPEN UNIX extension to BASE. 27228 In the DESCRIPTION, the definition of the depth argument is clarified. 27229 Issue 6 27230 The Open Group Base Resolution bwg97-003 is applied. | 27231 The wording of the mandatory [ELOOP] error condition is updated, and a second optional | 27232 [ELOOP] error condition is added. | System Interfaces, Issue 6 1343 nice( ) System Interfaces 27233 NAME 27234 nice - change the nice value of a process 27235 SYNOPSIS 27236 XSI #include 27237 int nice(int incr); 27238 27239 DESCRIPTION 27240 The nice( ) function shall add the value of incr to the nice value of the calling process. A process' 27241 nice value is a non-negative number for which a more positive value results in less favorable 27242 scheduling. 27243 A maximum nice value of 2*{NZERO}-1 and a minimum nice value of 0 are imposed by the 27244 system. Requests for values above or below these limits result in the nice value being set to the 27245 corresponding limit. Only a process with appropriate privileges can lower the nice value. 27246 PS|TPS Calling the nice( ) function has no effect on the priority of processes or threads with policy 27247 SCHED_FIFO or SCHED_RR. The effect on processes or threads with other scheduling policies 27248 is implementation-defined. | 27249 The nice value set with nice( ) shall be applied to the process. If the process is multi-threaded, the 27250 nice value shall affect all system scope threads in the process. 27251 As -1 is a permissible return value in a successful situation, an application wishing to check for 27252 error situations should set errno to 0, then call nice( ), and if it returns -1, check to see if errno is 27253 non-zero. 27254 RETURN VALUE 27255 Upon successful completion, nice( ) shall return the new nice value -{NZERO}. Otherwise, -1 27256 shall be returned, the process' nice value shall not be changed, and errno shall be set to indicate 27257 the error. 27258 ERRORS 27259 The nice( ) function shall fail if: 27260 [EPERM] The incr argument is negative and the calling process does not have | 27261 appropriate privileges. 27262 EXAMPLES 27263 Changing the Nice Value 27264 The following example adds the value of the incr argument, -20, to the nice value of the calling 27265 process. 27266 #include 27267 ... 27268 int incr = -20; 27269 int ret; 27270 ret = nice(incr); 27271 APPLICATION USAGE 27272 None. 1344 Technical Standard (2000) (Draft July 31, 2000) System Interfaces nice( ) 27273 RATIONALE 27274 None. 27275 FUTURE DIRECTIONS 27276 None. 27277 SEE ALSO 27278 The Base Definitions volume of IEEE Std. 1003.1-200x, , | 27279 CHANGE HISTORY 27280 First released in Issue 1. Derived from Issue 1 of the SVID. | 27281 Issue 4 27282 The header is added to the SYNOPSIS section. 27283 A statement is added to the DESCRIPTION indicating that the nice value can only be lowered by 27284 a process with appropriate privileges. 27285 Issue 4, Version 2 27286 The RETURN VALUE section is updated for X/OPEN UNIX conformance to define that the 27287 process' nice value is not changed if an error is detected. 27288 Issue 5 27289 A statement is added to the description indicating the effects of this function on the different 27290 scheduling policies and multi-threaded processes. System Interfaces, Issue 6 1345 nl_langinfo( ) System Interfaces 27291 NAME 27292 nl_langinfo - language information 27293 SYNOPSIS 27294 XSI #include 27295 char *nl_langinfo(nl_item item); 27296 27297 DESCRIPTION 27298 The nl_langinfo ( ) function shall return a pointer to a string containing information relevant to 27299 the particular language or cultural area defined in the program's locale (see ). The 27300 manifest constant names and values of item are defined in . For example: 27301 nl_langinfo(ABDAY_1) 27302 would return a pointer to the string "Dom" if the identified language was Portuguese, and 27303 "Sun" if the identified language was English. 27304 Calls to setlocale( ) with a category corresponding to the category of item (see ), or to 27305 the category LC_ALL, may overwrite the array pointed to by the return value. 27306 The nl_langinfo ( ) function need not be reentrant. A function that is not required to be reentrant is 27307 not required to be thread-safe. 27308 RETURN VALUE 27309 In a locale where langinfo data is not defined, nl_langinfo ( ) shall return a pointer to the 27310 corresponding string in the POSIX locale. In all locales, nl_langinfo ( ) shall return a pointer to an 27311 empty string if item contains an invalid setting. 27312 This pointer may point to static data that may be overwritten on the next call. 27313 ERRORS 27314 No errors are defined. 27315 EXAMPLES 27316 Getting Date and Time Formatting Information 27317 The following example returns a pointer to a string containing date and time formatting 27318 information, as defined in the LC_TIME category of the current locale. 27319 #include 27320 #include 27321 ... 27322 strftime(datestring, sizeof(datestring), nl_langinfo(D_T_FMT), tm); 27323 ... 27324 APPLICATION USAGE 27325 The array pointed to by the return value should not be modified by the program, but may be 27326 modified by further calls to nl_langinfo ( ). 27327 RATIONALE 27328 None. 27329 FUTURE DIRECTIONS 27330 None. 1346 Technical Standard (2000) (Draft July 31, 2000) System Interfaces nl_langinfo( ) 27331 SEE ALSO 27332 setlocale( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , , the | 27333 Base Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale | 27334 CHANGE HISTORY 27335 First released in Issue 2. 27336 Issue 4 27337 The header is removed from the SYNOPSIS section. 27338 Issue 5 27339 The last paragraph of the DESCRIPTION is moved from the APPLICATION USAGE section. 27340 A note indicating that this function need not be reentrant is added to the DESCRIPTION. System Interfaces, Issue 6 1347 nrand48( ) System Interfaces 27341 NAME 27342 nrand48 - generate uniformly distributed pseudo-random non-negative long integers 27343 SYNOPSIS 27344 XSI #include 27345 long nrand48(unsigned short xsubi[3]); | 27346 | 27347 DESCRIPTION 27348 Refer to drand48( ). 1348 Technical Standard (2000) (Draft July 31, 2000) System Interfaces ntohl( ) 27349 NAME 27350 ntohl - convert values between host and network byte order 27351 SYNOPSIS 27352 #include 27353 uint32_t ntohl(uint32_t netlong); 27354 DESCRIPTION 27355 Refer to htonl( ). System Interfaces, Issue 6 1349 ntohs( ) System Interfaces 27356 NAME 27357 ntohs - convert values between host and network byte order 27358 SYNOPSIS 27359 #include 27360 uint16_t ntohs(uint16_t netshort); 27361 DESCRIPTION 27362 Refer to htonl( ). 1350 Technical Standard (2000) (Draft July 31, 2000) System Interfaces open( ) 27363 NAME 27364 open - open a file 27365 SYNOPSIS 27366 OH #include 27367 #include 27368 int open(const char *path, int oflag, ... ); 27369 DESCRIPTION 27370 The open( ) function establishes the connection between a file and a file descriptor. It creates an 27371 open file description that refers to a file and a file descriptor that refers to that open file 27372 description. The file descriptor is used by other I/O functions to refer to that file. The path 27373 argument points to a path name naming the file. 27374 The open( ) function shall return a file descriptor for the named file that is the lowest file 27375 descriptor not currently open for that process. The open file description is new, and therefore the 27376 file descriptor does not share it with any other process in the system. The FD_CLOEXEC file 27377 descriptor flag associated with the new file descriptor shall be cleared. 27378 The file offset used to mark the current position within the file shall be set to the beginning of the 27379 file. 27380 The file status flags and file access modes of the open file description shall be set according to 27381 the value of oflag. 27382 Values for oflag are constructed by a bitwise-inclusive OR of flags from the following list, 27383 defined in . Applications shall specify exactly one of the first three values (file access 27384 modes) below in the value of oflag: 27385 O_RDONLY Open for reading only. 27386 O_WRONLY Open for writing only. 27387 O_RDWR Open for reading and writing. The result is undefined if this flag is applied to 27388 a FIFO. 27389 Any combination of the following may be used: 27390 O_APPEND If set, the file offset shall be set to the end of the file prior to each write. 27391 O_CREAT If the file exists, this flag has no effect except as noted under O_EXCL below. 27392 Otherwise, the file is created; the user ID of the file shall be set to the effective 27393 user ID of the process; the group ID of the file shall be set to the group ID of 27394 the file's parent directory or to the effective group ID of the process; and the 27395 access permission bits (see ) of the file mode shall be set to the 27396 value of the third argument taken as type mode_t modified as follows: a 27397 bitwise AND is performed on the file-mode bits and the corresponding bits in 27398 the complement of the process' file mode creation mask. Thus, all bits in the 27399 file mode whose corresponding bit in the file mode creation mask is set are 27400 cleared. When bits other than the file permission bits are set, the effect is 27401 unspecified. The third argument does not affect whether the file is open for 27402 reading, writing, or for both. 27403 SIO O_DSYNC Write I/O operations on the file descriptor complete as defined by 27404 synchronized I/O data integrity completion 27405 O_EXCL If O_CREAT and O_EXCL are set, open( ) shall fail if the file exists. The check 27406 for the existence of the file and the creation of the file if it does not exist shall 27407 be atomic with respect to other threads executing open( ) naming the same file | System Interfaces, Issue 6 1351 open( ) System Interfaces 27408 name in the same directory with O_EXCL and O_CREAT set. If O_EXCL and 27409 O_CREAT are set, and path names a symbolic link, open( ) shall fail and set 27410 errno to [EEXIST], regardless of the contents of the symbolic link. If O_EXCL is 27411 set and O_CREAT is not set, the result is undefined. 27412 O_NOCTTY If set and path identify a terminal device, open( ) shall not cause the terminal 27413 device to become the controlling terminal for the process. 27414 O_NONBLOCK When opening a FIFO with O_RDONLY or O_WRONLY set: 27415 * If O_NONBLOCK is set, an open( ) for reading-only shall return without | 27416 delay. An open( ) for writing-only shall return an error if no process | 27417 currently has the file open for reading. | 27418 * If O_NONBLOCK is clear, an open( ) for reading-only shall block the | 27419 calling thread until a thread opens the file for writing. An open( ) for | 27420 writing-only shall block the calling thread until a thread opens the file for | 27421 reading. 27422 When opening a block special or character special file that supports non- 27423 blocking opens: 27424 * If O_NONBLOCK is set, the open( ) function shall return without blocking 27425 for the device to be ready or available. Subsequent behavior of the device 27426 is device-specific. 27427 * If O_NONBLOCK is clear, the open( ) function shall block the calling 27428 thread until the device is ready or available before returning. 27429 Otherwise, the behavior of O_NONBLOCK is unspecified. 27430 SIO O_RSYNC Read I/O operations on the file descriptor complete at the same level of 27431 integrity as specified by the O_DSYNC and O_SYNC flags. If both O_DSYNC 27432 and O_RSYNC are set in oflag, all I/O operations on the file descriptor 27433 complete as defined by synchronized I/O data integrity completion. If both 27434 O_SYNC and O_RSYNC are set in flags, all I/O operations on the file 27435 descriptor complete as defined by synchronized I/O file integrity completion. 27436 SIO O_SYNC Write I/O operations on the file descriptor complete as defined by 27437 synchronized I/O file integrity completion. 27438 O_TRUNC If the file exists and is a regular file, and the file is successfully opened 27439 O_RDWR or O_WRONLY, its length is truncated to 0, and the mode and 27440 owner are unchanged. It shall have no effect on FIFO special files or terminal 27441 device files. Its effect on other file types is implementation-defined. The result | 27442 of using O_TRUNC with O_RDONLY is undefined. | 27443 If O_CREAT is set and the file did not previously exist, upon successful completion, open( ) shall 27444 mark for update the st_atime, st_ctime, and st_mtime fields of the file and the st_ctime and 27445 st_mtime fields of the parent directory. 27446 If O_TRUNC is set and the file did previously exist, upon successful completion, open( ) shall 27447 mark for update the st_ctime and st_mtime fields of the file. 27448 SIO If both the O_SYNC and O_DSYNC flags are set, the effect is as if only the O_SYNC flag was set. 27449 27450 XSR If path refers to a STREAMS file, oflag may be constructed from O_NONBLOCK OR'ed with 27451 either O_RDONLY, O_WRONLY, or O_RDWR. Other flag values are not applicable to 27452 STREAMS devices and have no effect on them. The value O_NONBLOCK affects the operation 1352 Technical Standard (2000) (Draft July 31, 2000) System Interfaces open( ) 27453 of STREAMS drivers and certain functions applied to file descriptors associated with STREAMS 27454 files. For STREAMS drivers, the implementation of O_NONBLOCK is device-specific. 27455 If path names the master side of a pseudo-terminal device, then it is unspecified whether open( ) 27456 locks the slave side so that it cannot be opened. Portable applications shall call unlockpt( ) before 27457 opening the slave side. 27458 The largest value that can be represented correctly in an object of type off_t shall be established | 27459 as the offset maximum in the open file description. | 27460 RETURN VALUE 27461 Upon successful completion, the function shall open the file and return a non-negative integer 27462 representing the lowest numbered unused file descriptor. Otherwise, -1 shall be returned and 27463 errno set to indicate the error. No files shall be created or modified if the function returns -1. 27464 ERRORS 27465 The open( ) function shall fail if: 27466 [EACCES] Search permission is denied on a component of the path prefix, or the file | 27467 exists and the permissions specified by oflag are denied, or the file does not 27468 exist and write permission is denied for the parent directory of the file to be 27469 created, or O_TRUNC is specified and write permission is denied. 27470 [EEXIST] O_CREAT and O_EXCL are set, and the named file exists. | 27471 [EINTR] A signal was caught during open( ). | 27472 SIO [EINVAL] The implementation does not support synchronized I/O for this file. | 27473 XSR [EIO] The path argument names a STREAMS file and a hangup or error occurred | 27474 during the open( ). 27475 [EISDIR] The named file is a directory and oflag includes O_WRONLY or O_RDWR. | 27476 [ELOOP] A loop exists in symbolic links encountered during resolution of the path | 27477 argument. | 27478 [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. | 27479 [ENAMETOOLONG] | 27480 The length of the path argument exceeds {PATH_MAX} or a path name 27481 component is longer than {NAME_MAX}. | 27482 [ENFILE] The maximum allowable number of files is currently open in the system. | 27483 [ENOENT] O_CREAT is not set and the named file does not exist; or O_CREAT is set and | 27484 either the path prefix does not exist or the path argument points to an empty 27485 string. 27486 XSR [ENOSR] The path argument names a STREAMS-based file and the system is unable to | 27487 allocate a STREAM. 27488 [ENOSPC] The directory or file system that would contain the new file cannot be | 27489 expanded, the file does not exist, and O_CREAT is specified. 27490 [ENOTDIR] A component of the path prefix is not a directory. | 27491 [ENXIO] O_NONBLOCK is set, the named file is a FIFO, O_WRONLY is set, and no | 27492 process has the file open for reading. | 27493 [ENXIO] The named file is a character special or block special file, and the device | 27494 associated with this special file does not exist. | System Interfaces, Issue 6 1353 open( ) System Interfaces 27495 [EOVERFLOW] The named file is a regular file and the size of the file cannot be represented | 27496 correctly in an object of type off_t. | 27497 [EROFS] The named file resides on a read-only file system and either O_WRONLY, | 27498 O_RDWR, O_CREAT (if file does not exist), or O_TRUNC is set in the oflag 27499 argument. 27500 The open( ) function may fail if: 27501 XSR [EAGAIN] The path argument names the slave side of a pseudo-terminal device that is | 27502 locked. | 27503 [EINVAL] The value of the oflag argument is not valid. | 27504 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 27505 resolution of the path argument. | 27506 [ENAMETOOLONG] | 27507 As a result of encountering a symbolic link in resolution of the path argument, 27508 the length of the substituted path name string exceeded {PATH_MAX}. | 27509 XSR [ENOMEM] The path argument names a STREAMS file and the system is unable to allocate | 27510 resources. | 27511 [ETXTBSY] The file is a pure procedure (shared text) file that is being executed and oflag is | 27512 O_WRONLY or O_RDWR. | 27513 EXAMPLES 27514 Opening a File for Writing by the Owner 27515 The following example opens the file /tmp/file, either by creating it (if it does not already exist), 27516 or by truncating its length to 0 (if it does exist). In the former case, if the call creates a new file, 27517 the access permission bits in the file mode of the file are set to permit reading and writing by the 27518 owner, and to permit reading only by group members and others. 27519 If the call to open( ) is successful, the file is opened for writing. 27520 #include 27521 ... 27522 int fd; 27523 mode_t mode = S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH; 27524 char *filename = "/tmp/file"; 27525 ... 27526 fd = open(filename, O_WRONLY | O_CREAT | O_TRUNC, mode); 27527 ... 27528 Opening a File Using an Existence Check 27529 The following example uses the open( ) function to try to create the LOCKFILE file and open it 27530 for writing. Because the open( ) function specifies the O_EXCL flag, the call fails if the file already 27531 exists. In that case, the program assumes that someone else is updating the password file and 27532 exits. 27533 #include 27534 #include 27535 #include 1354 Technical Standard (2000) (Draft July 31, 2000) System Interfaces open( ) 27536 #define LOCKFILE "/etc/ptmp" 27537 ... 27538 int pfd; /* Integer for file descriptor returned by open() call. */ 27539 ... 27540 if ((pfd = open(LOCKFILE, O_WRONLY | O_CREAT | O_EXCL, 27541 S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) == -1) 27542 { 27543 fprintf(stderr, "Cannot open /etc/ptmp. Try again later.\n"); 27544 exit(1); 27545 } 27546 ... 27547 Opening a File for Writing 27548 The following example opens a file for writing, creating the file if it does not already exist. If the 27549 file does exist, the system truncates the file to zero bytes. 27550 #include 27551 #include 27552 #include 27553 #define LOCKFILE "/etc/ptmp" 27554 ... 27555 int pfd; 27556 char filename[PATH_MAX+1]; 27557 ... 27558 if ((pfd = open(filename, O_WRONLY | O_CREAT | O_TRUNC, 27559 S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) == -1) 27560 { 27561 perror("Cannot open output file\n"); exit(1); 27562 } 27563 ... 27564 APPLICATION USAGE 27565 None. 27566 RATIONALE 27567 Except as specified in this volume of IEEE Std. 1003.1-200x, the flags allowed in oflag are not 27568 mutually-exclusive and any number of them may be used simultaneously. 27569 Some implementations permit opening FIFOs with O_RDWR. Since FIFOs could be 27570 implemented in other ways, and since two file descriptors can be used to the same effect, this 27571 possibility is left as undefined. 27572 See getgroups( ) about the group of a newly created file. 27573 The use of open( ) to create a regular file is preferable to the use of creat( ), because the latter is 27574 redundant and included only for historical reasons. 27575 The use of the O_TRUNC flag on FIFOs and directories (pipes cannot be open( )-ed) must be 27576 permissible without unexpected side effects (for example, creat( ) on a FIFO must not remove 27577 data). Because terminal special files might have type-ahead data stored in the buffer, O_TRUNC 27578 should not affect their content, particularly if a program that normally opens a regular file 27579 should open the current controlling terminal instead. Other file types, particularly | 27580 implementation-defined ones, are left implementation-defined. | System Interfaces, Issue 6 1355 open( ) System Interfaces 27581 IEEE Std. 1003.1-200x permits [EACCES] to be returned for conditions other than those explicitly | 27582 listed. | 27583 The O_NOCTTY flag was added to allow applications to avoid unintentionally acquiring a 27584 controlling terminal as a side effect of opening a terminal file. This volume of 27585 IEEE Std. 1003.1-200x does not specify how a controlling terminal is acquired, but it allows an 27586 implementation to provide this on open( ) if the O_NOCTTY flag is not set and other conditions 27587 specified in the Base Definitions volume of IEEE Std. 1003.1-200x, Chapter 11, General Terminal | 27588 Interface are met. The O_NOCTTY flag is an effective no-op if the file being opened is not a | 27589 terminal device. 27590 In historical implementations the value of O_RDONLY is zero. Because of that, it is not possible 27591 to detect the presence of O_RDONLY and another option. Future implementations should 27592 encode O_RDONLY and O_WRONLY as bit flags so that: 27593 O_RDONLY | O_WRONLY == O_RDWR 27594 In general, the open( ) function follows the symbolic link if path names a symbolic link. However, 27595 the open( ) function, when called with O_CREAT and O_EXCL, is required to fail with [EEXIST] 27596 if path names an existing symbolic link, even if the symbolic link refers to a nonexistent file. This 27597 behavior is required so that privileged applications can create a new file in a known location 27598 without the possibility that a symbolic link might cause the file to be created in a different 27599 location. 27600 For example, a privileged application that must create a file with a predictable name in a user- 27601 writable directory, such as the user's home directory, could be compromised if the user creates a 27602 symbolic link with that name that refers to a nonexistent file in a system directory. If the user can 27603 influence the contents of a file, the user could compromise the system by creating a new system 27604 configuration or spool file that would then be interpreted by the system. The test for a symbolic 27605 link which refers to a nonexisting file must be atomic with the creation of a new file. 27606 FUTURE DIRECTIONS 27607 None. 27608 SEE ALSO 27609 chmod( ), close( ), creat( ), dup( ), fcntl( ), lseek( ), read( ), umask( ), unlockpt( ), write( ), the Base | 27610 Definitions volume of IEEE Std. 1003.1-200x, , , | 27611 CHANGE HISTORY 27612 First released in Issue 1. Derived from Issue 1 of the SVID. | 27613 Issue 4 27614 The and headers are now marked as optional (OH); these headers do 27615 not need to be included on XSI-conformant systems. 27616 O_NDELAY is removed from the list of oflag values (this flag was marked WITHDRAWN in 27617 Issue 3). 27618 The [ENXIO] error (for the condition where the file is a character or block special file and the 27619 associated device does not exist) and the [EINVAL] error are marked as extensions. 27620 The following changes are incorporated for alignment with the ISO POSIX-1 standard: 27621 * The type of argument path is changed from char* to const char*. 27622 * Various wording changes are made to the DESCRIPTION to improve clarity and to align the 27623 text with the ISO POSIX-1 standard. 27624 The following changes are incorporated for alignment with the FIPS requirements: 1356 Technical Standard (2000) (Draft July 31, 2000) System Interfaces open( ) 27625 * In the DESCRIPTION, the description of O_CREAT is amended and the relevant part marked 27626 as an extension. 27627 * In the ERRORS section, the condition whereby [ENAMETOOLONG] is returned if a path 27628 name component is larger that {NAME_MAX} is now defined as mandatory and marked as 27629 an extension. 27630 Issue 4, Version 2 27631 The following changes are incorporated for X/OPEN UNIX conformance: 27632 * The DESCRIPTION is updated to define the use of open flags with STREAMS files, and to 27633 identify special considerations when opening the master side of a pseudo-terminal. 27634 * In the ERRORS section, the [EIO], [ELOOP], and [ENOSR] mandatory error conditions are 27635 added, and the [EAGAIN], [ENAMETOOLONG], and [ENOMEM] optional error conditions 27636 are added. 27637 Issue 5 27638 The DESCRIPTION is updated for alignment with the POSIX Realtime Extension and the POSIX 27639 Threads Extension. 27640 Large File Summit extensions are added. 27641 Issue 6 27642 In the SYNOPSIS, the inclusion of is no longer required. 27643 The following changes are made for alignment with the ISO POSIX-1: 1996 standard: 27644 * The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. 27645 This is since behavior may vary from one file system to another. 27646 The following new requirements on POSIX implementations derive from alignment with the 27647 Single UNIX Specification: 27648 * The requirement to include has been removed. Although was 27649 required for conforming implementations of previous POSIX specifications, it was not 27650 required for UNIX applications. 27651 * In the DESCRIPTION, O_CREAT is amended to state that the group ID of the file is set to the 27652 group ID of the file's parent directory or to the effective group ID of the process. This is a 27653 FIPS requirement. 27654 * In the DESCRIPTION, text is added to indicate setting of the offset maximum in the open file 27655 description. This change is to support large files. 27656 * In the ERRORS section, the [EOVERFLOW] condition is added. This change is to support 27657 large files. 27658 * The [ENXIO] mandatory error condition is added. 27659 * The [EINVAL], [ENAMETOOLONG], and [ETXTBSY] optional error conditions are added. 27660 The DESCRIPTION and ERRORS sections are updated so that items related to the optional XSI 27661 STREAMS Option Group are marked. 27662 The following changes were made to align with the IEEE P1003.1a draft standard: 27663 * An explanation is added of the effect of the O_CREAT and O_EXCL flags when the path 27664 refers to a symbolic link. 27665 * The [ELOOP] optional error condition is added. System Interfaces, Issue 6 1357 open( ) System Interfaces 27666 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. | 27667 The DESCRIPTION of O_EXCL is updated in response to IEEE PASC Interpretation 1003.1c #48. | 1358 Technical Standard (2000) (Draft July 31, 2000) System Interfaces opendir( ) 27668 NAME 27669 opendir - open a directory 27670 SYNOPSIS 27671 #include 27672 DIR *opendir(const char *dirname); 27673 DESCRIPTION 27674 The opendir( ) function shall open a directory stream corresponding to the directory named by 27675 the dirname argument. The directory stream is positioned at the first entry. If the type DIR is 27676 implemented using a file descriptor, applications shall only be able to open up to a total of 27677 {OPEN_MAX} files and directories. 27678 RETURN VALUE 27679 Upon successful completion, opendir( ) shall return a pointer to an object of type DIR. 27680 Otherwise, a null pointer shall be returned and errno set to indicate the error. 27681 ERRORS 27682 The opendir( ) function shall fail if: 27683 [EACCES] Search permission is denied for the component of the path prefix of dirname or | 27684 read permission is denied for dirname. | 27685 [ELOOP] A loop exists in symbolic links encountered during resolution of the dirname | 27686 argument. | 27687 [ENAMETOOLONG] | 27688 The length of the dirname argument exceeds {PATH_MAX} or a path name | 27689 component is longer than {NAME_MAX}. | 27690 [ENOENT] A component of dirname does not name an existing directory or dirname is an | 27691 empty string. 27692 [ENOTDIR] A component of dirname is not a directory. | 27693 The opendir( ) function may fail if: 27694 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 27695 resolution of the dirname argument. 27696 [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. | 27697 [ENAMETOOLONG] | 27698 As a result of encountering a symbolic link in resolution of the dirname 27699 argument, the length of the substituted path name string exceeded 27700 {PATH_MAX}. | 27701 [ENFILE] Too many files are currently open in the system. | 27702 EXAMPLES System Interfaces, Issue 6 1359 opendir( ) System Interfaces 27703 Open a Directory Stream 27704 The following program fragment demonstrates how the opendir( ) function is used. 27705 #include 27706 #include 27707 #include 27708 ... 27709 DIR *dir; 27710 struct dirent *dp; 27711 ... 27712 if ((dir = opendir (".")) == NULL) { 27713 perror ("Cannot open ."); 27714 exit (1); 27715 } 27716 while ((dp = readdir (dir)) != NULL) { 27717 ... 27718 APPLICATION USAGE 27719 The opendir( ) function should be used in conjunction with readdir( ), closedir( ), and rewinddir( ) to 27720 examine the contents of the directory (see the EXAMPLES section in readdir( )). This method is 27721 recommended for portability. 27722 RATIONALE 27723 Based on historical implementations, the rules about file descriptors apply to directory streams 27724 as well. However, this volume of IEEE Std. 1003.1-200x does not mandate that the directory 27725 stream be implemented using file descriptors. The description of closedir( ) clarifies that if a file | 27726 descriptor is used for the directory stream, it is mandatory that closedir( ) deallocate the file 27727 descriptor. When a file descriptor is used to implement the directory stream, it behaves as if the 27728 FD_CLOEXEC had been set for the file descriptor. 27729 The directory entries for dot and dot-dot are optional. This volume of IEEE Std. 1003.1-200x does | 27730 not provide a way to test a priori for their existence because an application that is portable must 27731 be written to look for (and usually ignore) those entries. Writing code that presumes that they 27732 are the first two entries does not always work, as many implementations permit them to be 27733 other than the first two entries, with a ``normal'' entry preceding them. There is negligible value 27734 in providing a way to determine what the implementation does because the code to deal with 27735 dot and dot-dot must be written in any case and because such a flag would add to the list of 27736 those flags (which has proven in itself to be objectionable) and might be abused. 27737 Since the structure and buffer allocation, if any, for directory operations are defined by the 27738 implementation, this volume of IEEE Std. 1003.1-200x imposes no portability requirements for 27739 erroneous program constructs, erroneous data, or the use of indeterminate values such as the 27740 use or referencing of a dirp value or a dirent structure value after a directory stream has been 27741 closed or after a fork( ) or one of the exec function calls. | 27742 FUTURE DIRECTIONS 27743 None. 27744 SEE ALSO 27745 closedir( ), lstat( ), readdir( ), rewinddir( ), symlink( ), the Base Definitions volume of | 27746 IEEE Std. 1003.1-200x, , , | 1360 Technical Standard (2000) (Draft July 31, 2000) System Interfaces opendir( ) 27747 CHANGE HISTORY 27748 First released in Issue 2. 27749 Issue 4 27750 The header is now marked as optional (OH); this header need not be included on 27751 XSI-conformant systems. 27752 In the DESCRIPTION, the following sentence is moved to the Base Definitions volume of | 27753 IEEE Std. 1003.1-200x: ``The type DIR, which is defined in , represents a directory | 27754 stream, which is an ordered sequence of all directory entries in a particular directory.'' 27755 The following changes are incorporated for alignment with the ISO POSIX-1 standard: 27756 * The type of argument dirname is changed from char* to const char*. 27757 * The generation of an [ENOENT] error when dirname points to an empty string is made | 27758 mandatory. 27759 The following change is incorporated for alignment with the FIPS requirements: 27760 * In the ERRORS section, the condition whereby [ENAMETOOLONG] is returned if a path | 27761 name component is larger that {NAME_MAX} is now defined as mandatory and marked as 27762 an extension. 27763 Issue 4, Version 2 27764 The ERRORS section is updated for X/OPEN UNIX conformance as follows: 27765 * It states that [ELOOP] is returned if too many symbolic links are encountered during path 27766 name resolution. 27767 * A second [ENAMETOOLONG] condition is defined that may report excessive length of an 27768 intermediate result of path name resolution of a symbolic link. 27769 Issue 6 27770 In the SYNOPSIS, the inclusion of is no longer required. 27771 The following changes are made for alignment with the ISO POSIX-1: 1996 standard: 27772 * The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. 27773 This is since behavior may vary from one file system to another. 27774 The following new requirements on POSIX implementations derive from alignment with the 27775 Single UNIX Specification: 27776 * The requirement to include has been removed. Although was 27777 required for conforming implementations of previous POSIX specifications, it was not 27778 required for UNIX applications. 27779 * The [ELOOP] mandatory error condition is added. 27780 * A second [ENAMETOOLONG] is added as an optional error condition. 27781 The following changes were made to align with the IEEE P1003.1a draft standard: 27782 * The [ELOOP] optional error condition is added. System Interfaces, Issue 6 1361 openlog( ) System Interfaces 27783 NAME 27784 openlog - open a connection to the logging facility 27785 SYNOPSIS 27786 XSI #include 27787 void openlog(const char *ident, int logopt, int facility); 27788 27789 DESCRIPTION 27790 Refer to closelog( ). 1362 Technical Standard (2000) (Draft July 31, 2000) System Interfaces optarg 27791 NAME 27792 optarg, opterr, optind, optopt - options parsing variables 27793 SYNOPSIS 27794 #include 27795 extern char *optarg; 27796 extern int opterr, optind, optopt; 27797 DESCRIPTION 27798 Refer to getopt( ). System Interfaces, Issue 6 1363 pathconf( ) System Interfaces 27799 NAME 27800 pathconf - get configurable path name variables 27801 SYNOPSIS 27802 #include 27803 long pathconf(const char *path, int name); | 27804 DESCRIPTION | 27805 Refer to fpathconf( ). 1364 Technical Standard (2000) (Draft July 31, 2000) System Interfaces pause( ) 27806 NAME 27807 pause - suspend the thread until a signal is received 27808 SYNOPSIS 27809 #include 27810 int pause(void); 27811 DESCRIPTION 27812 The pause( ) function shall suspend the calling thread until delivery of a signal whose action is 27813 either to execute a signal-catching function or to terminate the process. 27814 If the action is to terminate the process, pause( ) shall not return. 27815 If the action is to execute a signal-catching function, pause( ) shall return after the signal-catching 27816 function returns. 27817 RETURN VALUE 27818 Since pause( ) suspends thread execution indefinitely unless interrupted by a signal, there is no 27819 successful completion return value. A value of -1 shall be returned and errno set to indicate the 27820 error. 27821 ERRORS 27822 The pause( ) function shall fail if: 27823 [EINTR] A signal is caught by the calling process and control is returned from the | 27824 signal-catching function. 27825 EXAMPLES 27826 None. 27827 APPLICATION USAGE 27828 Many common uses of pause( ) have timing windows. The scenario involves checking a 27829 condition related to a signal and, if the signal has not occurred, calling pause( ). When the signal 27830 occurs between the check and the call to pause( ), the process often blocks indefinitely. The 27831 sigprocmask( ) and sigsuspend( ) functions can be used to avoid this type of problem. 27832 RATIONALE 27833 None. 27834 FUTURE DIRECTIONS 27835 None. 27836 SEE ALSO 27837 sigsuspend( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 27838 CHANGE HISTORY 27839 First released in Issue 1. Derived from Issue 1 of the SVID. | 27840 Issue 4 27841 The header is added to the SYNOPSIS section. 27842 In the RETURN VALUE section, the text is expanded to indicate that process execution is 27843 suspended indefinitely ``unless interrupted by a signal''. 27844 The following change is incorporated for alignment with the ISO POSIX-1 standard: 27845 * The argument list is explicitly defined as void. System Interfaces, Issue 6 1365 pause( ) System Interfaces 27846 Issue 5 27847 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 27848 Issue 6 27849 The APPLICATION USAGE section is added. 1366 Technical Standard (2000) (Draft July 31, 2000) System Interfaces pclose( ) 27850 NAME 27851 pclose - close a pipe stream to or from a process 27852 SYNOPSIS 27853 #include 27854 int pclose(FILE *stream); 27855 DESCRIPTION 27856 The pclose( ) function shall close a stream that was opened by popen( ), wait for the command to 27857 terminate, and return the termination status of the process that was running the command 27858 language interpreter. However, if a call caused the termination status to be unavailable to 27859 pclose( ), then pclose( ) shall return -1 with errno set to [ECHILD] to report this situation. This can 27860 happen if the application calls one of the following functions: 27861 * wait( ) 27862 * waitpid ( ) with a pid argument less than or equal to 0 or equal to the process ID of the 27863 command line interpreter 27864 * Any other function not defined in this volume of IEEE Std. 1003.1-200x that could do one of 27865 the above 27866 In any case, pclose( ) shall not return before the child process created by popen( ) has terminated. 27867 If the command language interpreter cannot be executed, the child termination status returned 27868 by pclose( ) is as if the command language interpreter terminated using exit(127) or _exit(127). 27869 The pclose( ) function shall not affect the termination status of any child of the calling process 27870 other than the one created by popen( ) for the associated stream. 27871 If the argument stream to pclose( ) is not a pointer to a stream created by popen( ), the result of 27872 pclose( ) is undefined. 27873 RETURN VALUE 27874 Upon successful return, pclose( ) shall return the termination status of the command language 27875 interpreter. Otherwise, pclose( ) shall return -1 and set errno to indicate the error. 27876 ERRORS 27877 The pclose( ) function shall fail if: 27878 [ECHILD] The status of the child process could not be obtained, as described above. | 27879 EXAMPLES 27880 None. 27881 APPLICATION USAGE 27882 None. 27883 RATIONALE 27884 There is a requirement that pclose( ) not return before the child process terminates. This is 27885 intended to disallow implementations that return [EINTR] if a signal is received while waiting. 27886 If pclose( ) returned before the child terminated, there would be no way for the application to 27887 discover which child used to be associated with the stream, and it could not do the cleanup 27888 itself. 27889 If the stream pointed to by stream was not created by popen( ), historical implementations of 27890 pclose( ) return -1 without setting errno. To avoid requiring pclose( ) to set errno in this case, 27891 IEEE Std. 1003.1-200x makes the behavior unspecified. An application should not use pclose( ) to 27892 close any stream that was not created by popen( ). System Interfaces, Issue 6 1367 pclose( ) System Interfaces 27893 Some historical implementations of pclose( ) either block or ignore the signals SIGINT, SIGQUIT, 27894 and SIGHUP while waiting for the child process to terminate. Since this behavior is not 27895 described for the pclose( ) function in IEEE Std. 1003.1-200x, such implementations are not 27896 conforming. Also, some historical implementations return [EINTR] if a signal is received, even 27897 though the child process has not terminated. Such implementations are also considered non- 27898 conforming. 27899 Consider, for example, an application that uses: 27900 popen("command", "r") 27901 to start command, which is part of the same application. The parent writes a prompt to its 27902 standard output (presumably the terminal) and then reads from the stream. The child reads the | 27903 response from the user, does some transformation on the response (path name expansion, | 27904 perhaps) and writes the result to its standard output. The parent process reads the result from 27905 the pipe, does something with it, and prints another prompt. The cycle repeats. Assuming that 27906 both processes do appropriate buffer flushing, this would be expected to work. | 27907 To conform to IEEE Std. 1003.1-200x, pclose( ) must use waitpid( ), or some similar function, | 27908 instead of wait( ). 27909 The code sample below illustrates how the pclose( ) function might be implemented on a system 27910 conforming to IEEE Std. 1003.1-200x. 27911 int pclose(FILE *stream) 27912 { 27913 int stat; 27914 pid_t pid; 27915 pid = 27916 (void) fclose(stream); 27917 while (waitpid(pid, &stat, 0) == -1) { 27918 if (errno != EINTR){ 27919 stat = -1; 27920 break; 27921 } 27922 } 27923 return(stat); 27924 } 27925 FUTURE DIRECTIONS 27926 None. 27927 SEE ALSO 27928 fork( ), popen( ), waitpid( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 27929 CHANGE HISTORY 27930 First released in Issue 1. Derived from Issue 1 of the SVID. | 27931 Issue 4 27932 The following changes are incorporated for alignment with the ISO POSIX-2 standard: 27933 * The function is no longer marked as an extension. 27934 * The simple DESCRIPTION given in Issue 3 is replaced with a more complete description in 27935 this issue. In particular, interactions between this function and wait( ) and waitpid( ) are 27936 defined. 1368 Technical Standard (2000) (Draft July 31, 2000) System Interfaces perror( ) 27937 NAME 27938 perror - write error messages to standard error 27939 SYNOPSIS 27940 #include 27941 void perror(const char *s); 27942 DESCRIPTION 27943 CX The functionality described on this reference page is aligned with the ISO C standard. Any 27944 conflict between the requirements described here and the ISO C standard is unintentional. This 27945 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 27946 The perror( ) function maps the error number accessed through the symbol errno to a language- 27947 dependent error message, which shall be written to the standard error stream as follows: 27948 * First (if s is not a null pointer and the character pointed to by s is not the null byte), the string 27949 pointed to by s followed by a colon and a character. 27950 * Then an error message string followed by a character. 27951 The contents of the error message strings are the same as those returned by strerror( ) with 27952 argument errno. 27953 CX The perror( ) function shall mark the file associated with the standard error stream as having 27954 been written (st_ctime, st_mtime marked for update) at some time between its successful 27955 completion and exit( ), abort( ), or the completion of fflush( ) or fclose( ) on stderr. 27956 The perror( ) function shall not change the orientation of the standard error stream. 27957 RETURN VALUE 27958 The perror( ) function shall return no value. 27959 ERRORS 27960 No errors are defined. 27961 EXAMPLES 27962 Printing an Error Message for a Function 27963 The following example replaces bufptr with a buffer that is the necessary size. If an error occurs, 27964 the perror( ) function prints a message and the program exits. 27965 #include 27966 #include 27967 ... 27968 char *bufptr; 27969 size_t szbuf; 27970 ... 27971 if ((bufptr = malloc(szbuf)) == NULL) { 27972 perror("malloc"); exit(2); 27973 } 27974 ... 27975 APPLICATION USAGE 27976 None. System Interfaces, Issue 6 1369 perror( ) System Interfaces 27977 RATIONALE 27978 None. 27979 FUTURE DIRECTIONS 27980 None. 27981 SEE ALSO 27982 strerror( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 27983 CHANGE HISTORY 27984 First released in Issue 1. Derived from Issue 1 of the SVID. | 27985 Issue 4 27986 The language for error message strings was given as implementation-defined in Issue 3. In this | 27987 issue, they are defined as language-dependent. | 27988 The following change is incorporated for alignment with the ISO POSIX-1 standard: 27989 * A paragraph is added to the DESCRIPTION defining the effects of this function on the 27990 st_ctime and st_mtime fields of the standard error stream. 27991 The following change is incorporated for alignment with the ISO C standard: 27992 * The type of argument s is changed from char* to const char*. 27993 Issue 5 27994 A paragraph is added to the DESCRIPTION indicating that perror( ) does not change the 27995 orientation of the standard error stream. 27996 Issue 6 27997 Extensions beyond the ISO C standard are now marked. 1370 Technical Standard (2000) (Draft July 31, 2000) System Interfaces pipe( ) 27998 NAME 27999 pipe - create an interprocess channel 28000 SYNOPSIS 28001 #include 28002 int pipe(int fildes[2]); 28003 DESCRIPTION 28004 The pipe( ) function shall create a pipe and place two file descriptors, one each into the 28005 arguments fildes[0] and fildes[1], that refer to the open file descriptions for the read and write 28006 ends of the pipe. Their integer values shall be the two lowest available at the time of the pipe( ) 28007 call. The O_NONBLOCK and FD_CLOEXEC flags shall be clear on both file descriptors. (The 28008 fcntl( ) function can be used to set both these flags.) 28009 Data can be written to the file descriptor fildes[1] and read from the file descriptor fildes[0]. A 28010 read on the file descriptor fildes[0] shall access data written to the file descriptor fildes[1] on a | 28011 first-in-first-out basis. It is unspecified whether fildes[0] is also open for writing and whether | 28012 fildes[1] is also open for reading. | 28013 A process has the pipe open for reading (correspondingly writing) if it has a file descriptor open 28014 that refers to the read end, fildes[0] (write end, fildes[1]). 28015 Upon successful completion, pipe( ) shall mark for update the st_atime, st_ctime, and st_mtime 28016 fields of the pipe. 28017 RETURN VALUE 28018 Upon successful completion, 0 shall be returned; otherwise, -1 shall be returned and errno set to 28019 indicate the error. 28020 ERRORS 28021 The pipe( ) function shall fail if: 28022 [EMFILE] More than {OPEN_MAX} minus two file descriptors are already in use by this | 28023 process. 28024 [ENFILE] The number of simultaneously open files in the system would exceed a | 28025 system-imposed limit. 28026 EXAMPLES 28027 None. 28028 APPLICATION USAGE 28029 None. 28030 RATIONALE 28031 The wording carefully avoids using the verb ``to open'' in order to avoid any implication of use 28032 of open( ); see also write( ). 28033 FUTURE DIRECTIONS 28034 None. 28035 SEE ALSO 28036 fcntl( ), read( ), write( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , | 28037 28038 CHANGE HISTORY 28039 First released in Issue 1. Derived from Issue 1 of the SVID. | System Interfaces, Issue 6 1371 pipe( ) System Interfaces 28040 Issue 4 28041 The header is added to the SYNOPSIS section. 28042 Issue 4, Version 2 28043 The DESCRIPTION is updated for X/OPEN UNIX conformance to indicate that certain 28044 dispositions of fildes[0] and fildes[1] are unspecified. 28045 Issue 6 28046 The following new requirements on POSIX implementations derive from alignment with the 28047 Single UNIX Specification: 28048 * The DESCRIPTION is updated to indicate that certain dispositions of fildes[0] and fildes[1] 28049 are unspecified. 1372 Technical Standard (2000) (Draft July 31, 2000) System Interfaces poll( ) 28050 NAME 28051 poll - input/output multiplexing 28052 SYNOPSIS 28053 XSI #include 28054 int poll(struct pollfd fds[], nfds_t nfds, int timeout); 28055 28056 DESCRIPTION 28057 The poll( ) function provides applications with a mechanism for multiplexing input/output over 28058 a set of file descriptors. For each member of the array pointed to by fds, poll( ) examines the given 28059 file descriptor for the event(s) specified in events. The number of pollfd structures in the fds 28060 array is specified by nfds. The poll( ) function identifies those file descriptors on which an 28061 application can read or write data, or on which certain events have occurred. 28062 The fds argument specifies the file descriptors to be examined and the events of interest for each 28063 file descriptor. It is a pointer to an array with one member for each open file descriptor of 28064 interest. The array's members are pollfd structures within which fd specifies an open file 28065 descriptor and events and revents are bitmasks constructed by OR'ing a combination of the 28066 following event flags: 28067 XSR POLLIN Data other than high-priority data may be read without blocking. For 28068 STREAMS, this flag is set in revents even if the message is of zero length. 28069 XSR POLLRDNORM Normal data (priority band equals 0) may be read without blocking. For 28070 STREAMS, this flag is set in revents even if the message is of zero length. 28071 XSR POLLRDBAND Data from a non-zero priority band may be read without blocking. For 28072 STREAMS, this flag is set in revents even if the message is of zero length. 28073 XSR POLLPRI High-priority data may be received without blocking. For STREAMS, this flag 28074 is set in revents even if the message is of zero length. 28075 POLLOUT Normal data (priority band equals 0) may be written without blocking. 28076 POLLWRNORM Same as POLLOUT. 28077 POLLWRBAND Priority data (priority band >0) may be written. This event only examines 28078 bands that have been written to at least once. 28079 POLLERR An error has occurred on the device or stream. This flag is only valid in the 28080 revents bitmask; it is ignored in the events member. 28081 POLLHUP The device has been disconnected. This event and POLLOUT are mutually- 28082 exclusive; a stream can never be writable if a hangup has occurred. However, 28083 this event and POLLIN, POLLRDNORM, POLLRDBAND, or POLLPRI are not 28084 mutually-exclusive. This flag is only valid in the revents bitmask; it is ignored 28085 in the events member. 28086 POLLNVAL The specified fd value is invalid. This flag is only valid in the revents member; 28087 it is ignored in the events member. 28088 If the value of fd is less than 0, events is ignored, and revents is set to 0 in that entry on return from 28089 poll( ). 28090 In each pollfd structure, poll( ) clears the revents member, except that where the application 28091 requested a report on a condition by setting one of the bits of events listed above, poll( ) sets the 28092 corresponding bit in revents if the requested condition is true. In addition, poll( ) sets the 28093 POLLHUP, POLLERR, and POLLNVAL flag in revents if the condition is true, even if the System Interfaces, Issue 6 1373 poll( ) System Interfaces 28094 application did not set the corresponding bit in events. 28095 If none of the defined events have occurred on any selected file descriptor, poll( ) waits at least 28096 timeout milliseconds for an event to occur on any of the selected file descriptors. If the value of 28097 timeout is 0, poll( ) shall return immediately. If the value of timeout is -1, poll( ) shall block until a 28098 requested event occurs or until the call is interrupted. 28099 Implementations may place limitations on the granularity of timeout intervals. If the requested 28100 timeout interval requires a finer granularity than the implementation supports, the actual 28101 timeout interval shall be rounded up to the next supported value. 28102 The poll( ) function is not affected by the O_NONBLOCK flag. 28103 XSR The poll( ) function supports regular files, terminal and pseudo-terminal devices, STREAMS- 28104 based files,FIFOs, pipes, and sockets. The behavior of poll( ) on elements of fds that refer to other | 28105 types of file is unspecified. 28106 Regular files always poll TRUE for reading and writing. 28107 The poll( ) function supports sockets. 28108 A file descriptor for a socket that is listening for connections shall indicate that it is ready for 28109 reading, once connections are available. A file descriptor for a socket that is connecting 28110 asynchronously shall indicate that it is ready for writing, once a connection has been established. 28111 RETURN VALUE 28112 Upon successful completion, poll( ) shall return a non-negative value. A positive value indicates 28113 the total number of file descriptors that have been selected (that is, file descriptors for which the 28114 revents member is non-zero). A value of 0 indicates that the call timed out and no file descriptors 28115 have been selected. Upon failure, poll( ) shall return -1 and set errno to indicate the error. 28116 ERRORS 28117 The poll( ) function shall fail if: 28118 [EAGAIN] The allocation of internal data structures failed but a subsequent request may | 28119 succeed. 28120 [EINTR] A signal was caught during poll( ). | 28121 XSR [EINVAL] The nfds argument is greater than {OPEN_MAX}, or one of the fd members | 28122 refers to a STREAM or multiplexer that is linked (directly or indirectly) 28123 downstream from a multiplexer. 28124 EXAMPLES 28125 Checking for Events on a Stream 28126 The following example opens a pair of STREAMS devices and then waits for either one to | 28127 become writable. This example proceeds as follows: | 28128 1. Sets the timeout parameter to 500 milliseconds. 28129 2. Opens the STREAMS devices /dev/dev0 and /dev/dev1, and then polls them, specifying 28130 POLLOUT and POLLWRBAND as the events of interest. 28131 The STREAMS device names /dev/dev0 and /dev/dev1 are only examples of how 28132 STREAMS devices can be named; STREAMS naming conventions may vary among 28133 systems conforming to the IEEE Std. 1003.1-200x. 28134 3. Uses the ret variable to determine whether an event has occurred on either of the two 28135 STREAMS. The poll( ) function is given 500 milliseconds to wait for an event to occur (if it 1374 Technical Standard (2000) (Draft July 31, 2000) System Interfaces poll( ) 28136 has not occurred prior to the poll( ) call). 28137 4. Checks the returned value of ret. If a positive value is returned, one of the following can 28138 be done: 28139 a. Priority data can be written to the open STREAM on priority bands greater than 0, 28140 because the POLLWRBAND event occurred on the open STREAM (fds[0] or fds[1]). 28141 b. Data can be written to the open STREAM on priority-band 0, because the POLLOUT 28142 event occurred on the open STREAM (fds[0] or fds[1]). 28143 5. If the returned value is not a positive value, permission to write data to the open STREAM 28144 (on any priority band) is denied. 28145 6. If the POLLHUP event occurs on the open STREAM (fds[0] or fds[1]), the device on the 28146 open STREAM has disconnected. 28147 #include 28148 #include 28149 ... 28150 struct pollfd fds[2]; 28151 int timeout_msecs = 500; 28152 int ret; 28153 int i; 28154 /* Open STREAMS device. */ 28155 fds[0].fd = open("/dev/dev0", ...); 28156 fds[1].fd = open("/dev/dev1", ...); 28157 fds[0].events = POLLOUT | POLLWRBAND; 28158 fds[1].events = POLLOUT | POLLWRBAND; 28159 ret = poll(fds, 2, timeout_msecs); 28160 if (ret > 0) { 28161 /* An event on one of the fds has occurred. */ 28162 for (i=0; i<2; i++) { 28163 if (fds[i].revents & POLLWRBAND) { 28164 /* Priority data may be written on device number i. */ 28165 ... 28166 } 28167 if (fds[i].revents & POLLOUT) { 28168 /* Data may be written on device number i. */ 28169 ... 28170 } 28171 if (fds[i].revents & POLLHUP) { 28172 /* A hangup has occurred on device number i. */ 28173 ... 28174 } 28175 } 28176 } 28177 APPLICATION USAGE 28178 None. System Interfaces, Issue 6 1375 poll( ) System Interfaces 28179 RATIONALE 28180 None. 28181 FUTURE DIRECTIONS 28182 None. 28183 SEE ALSO 28184 getmsg( ), putmsg( ), read( ), select( ), write( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 28185 , , Section 2.6 (on page 539) 28186 CHANGE HISTORY 28187 First released in Issue 4, Version 2. 28188 Issue 5 28189 Moved from X/OPEN UNIX extension to BASE. 28190 The description of POLLWRBAND is updated. 28191 Issue 6 28192 Text referring to sockets is added to the DESCRIPTION. 28193 Text relating to the XSI STREAMS Option Group is marked. 1376 Technical Standard (2000) (Draft July 31, 2000) System Interfaces popen( ) 28194 NAME 28195 popen - initiate pipe streams to or from a process 28196 SYNOPSIS 28197 #include 28198 FILE *popen(const char *command, const char *mode); 28199 DESCRIPTION 28200 The popen( ) function shall execute the command specified by the string command. It creates a 28201 pipe between the calling program and the executed command, and returns a pointer to a stream 28202 that can be used to either read from or write to the pipe. 28203 The environment of the executed command shall be as if a child process were created within the 28204 popen( ) call using the fork( ) function, and the child used execl( ) to invoke a command line 28205 interpreter. 28206 If the implementation supports the Shell and Utilities volume of IEEE Std. 1003.1-200x, the | 28207 environment of the executed command is as if a child process were created within the popen( ) | 28208 call using fork( ), and the child invoked the sh utility using the call: 28209 execl(shell path, "sh", "-c", command, (char *)0); 28210 where shell path is an unspecified path name for the sh utility. 28211 The popen( ) function ensures that any streams from previous popen( ) calls that remain open in 28212 the parent process are closed in the new child process. 28213 The mode argument to popen( ) is a string that specifies I/O mode: 28214 1. If mode is r, when the child process is started, its file descriptor STDOUT_FILENO shall be 28215 the writable end of the pipe, and the file descriptor fileno(stream) in the calling process, 28216 where stream is the stream pointer returned by popen( ), shall be the readable end of the 28217 pipe. 28218 2. If mode is w, when the child process is started its file descriptor STDIN_FILENO shall be 28219 the readable end of the pipe, and the file descriptor fileno(stream) in the calling process, 28220 where stream is the stream pointer returned by popen( ), shall be the writable end of the 28221 pipe. 28222 3. If mode is any other value, the result is undefined. 28223 After popen( ), both the parent and the child process shall be capable of executing independently 28224 before either terminates. 28225 Pipe streams are byte-oriented. 28226 RETURN VALUE 28227 Upon successful completion, popen( ) shall return a pointer to an open stream that can be used to 28228 read or write to the pipe. Otherwise, it shall return a null pointer and may set errno to indicate 28229 the error. 28230 ERRORS 28231 The popen( ) function may fail if: 28232 [EMFILE] {FOPEN_MAX} or {STREAM_MAX} streams are currently open in the calling | 28233 process. | 28234 [EINVAL] The mode argument is invalid. | 28235 The popen( ) function may also set errno values as described by fork( ) or pipe( ). System Interfaces, Issue 6 1377 popen( ) System Interfaces 28236 EXAMPLES 28237 None. 28238 APPLICATION USAGE 28239 Because open files are shared, a mode r command can be used as an input filter and a mode w 28240 command as an output filter. 28241 Buffered reading before opening an input filter may leave the standard input of that filter 28242 mispositioned. Similar problems with an output filter may be prevented by careful buffer 28243 flushing; for example, with fflush( ). 28244 A stream opened by popen( ) should be closed by pclose( ). 28245 The behavior of popen( ) is specified for values of mode of r and w. Other modes such as rb and 28246 wb might be supported by specific implementations, but these would not be portable features. 28247 Note that historical implementations of popen( ) only check to see if the first character of mode is 28248 r. Thus, a mode of robert the robot would be treated as mode r, and a mode of anything else would be 28249 treated as mode w. 28250 If the application calls waitpid( ) or waitid( ) with a pid argument greater than 0, and it still has a 28251 stream that was called with popen( ) open, it must ensure that pid does not refer to the process 28252 started by popen( ). 28253 To determine whether or not the environment specified in the Shell and Utilities volume of | 28254 IEEE Std. 1003.1-200x is present, use the function call: | 28255 sysconf(_SC_2_VERSION) 28256 (See sysconf( )). 28257 RATIONALE 28258 The popen( ) function should not be used by programs that have set user (or group) ID privileges. 28259 The fork( ) and exec family of functions (except execlp( ) and execvp( )), should be used instead. 28260 This prevents any unforeseen manipulation of the environment of the user that could cause 28261 execution of commands not anticipated by the calling program. 28262 If the original and popen( )ed processes both intend to read or write or read and write a common | 28263 file, and either will be using FILE-type C functions (fread( ), fwrite( ), and so on), the rules for | 28264 sharing file handles must be observed (see Section 2.5.1 (on page 535)). | 28265 Because open files are shared, a mode r argument can be used as an input filter and a mode w | 28266 argument as an output filter. | 28267 The behavior of popen( ) is specified for modes of r and w. Other modes such as rb and wb might | 28268 be supported by specific implementations, but these would not be portable features. Note that 28269 historical implementations of popen( ) only check to see if the first character of mode is 'r'. 28270 Thus, a mode of robert the robot would be treated as mode r, and a mode of anything else would be | 28271 treated as mode w. | 28272 If the application calls waitpid( ) with a pid argument greater than zero, and it still has a 28273 popen( )ed stream open, it must ensure that pid does not refer to the process started by popen( ). 28274 FUTURE DIRECTIONS 28275 None. 28276 SEE ALSO 28277 pclose( ), pipe( ), sysconf( ), system( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 28278 , the Shell and Utilities volume of IEEE Std. 1003.1-200x | 1378 Technical Standard (2000) (Draft July 31, 2000) System Interfaces popen( ) 28279 CHANGE HISTORY 28280 First released in Issue 1. Derived from Issue 1 of the SVID. | 28281 Issue 4 28282 The APPLICATION USAGE section is extended. Only notes about buffer flushing are retained 28283 from Issue 3. 28284 The following changes are incorporated for alignment with the ISO POSIX-2 standard: 28285 * The function is no longer marked as an extension. 28286 * The type of arguments command and mode are changed from char* to const char*. 28287 * The DESCRIPTION is completely rewritten for alignment with the ISO POSIX-2 standard, 28288 although it describes essentially the same functionality as Issue 3. 28289 * The sh utility defined in the Shell and Utilities volume of IEEE Std. 1003.1-200x is no longer | 28290 required in all circumstances. | 28291 * The ERRORS section is added. 28292 Issue 5 28293 A statement is added to the DESCRIPTION indicating that pipe streams are byte-oriented. 28294 Issue 6 28295 The following new requirements on POSIX implementations derive from alignment with the 28296 Single UNIX Specification: 28297 * The optional [EMFILE] error condition is added. 28298 The following changes were made to align with the IEEE P1003.1a draft standard: 28299 * The DESCRIPTION is adjusted to reflect the behavior on systems that do not support the | 28300 Shell option. | System Interfaces, Issue 6 1379 posix_fadvise( ) System Interfaces 28301 NAME 28302 posix_fadvise - file advisory information 28303 SYNOPSIS 28304 ADV #include 28305 int posix_fadvise(int fd, off_t offset, size_t len, int advice); 28306 28307 DESCRIPTION 28308 The posix_fadvise( ) function provides advice to the implementation on the expected behavior of 28309 the application with respect to the data in the file associated with the open file descriptor, fd, 28310 starting at offset and continuing for len bytes. The specified range need not currently exist in the 28311 file. If len is zero, all data following offset is specified. The implementation may use this 28312 information to optimize handling of the specified data. The posix_fadvise( ) function has no effect 28313 on the semantics of other operations on the specified data, although it may affect the | 28314 performance of other operations. | 28315 The advice to be applied to the data is specified by the advice parameter and may be one of the 28316 following values: 28317 POSIX_FADV_NORMAL 28318 Specifies that the application has no advice to give on its behavior with respect to the 28319 specified data. It is the default characteristic if no advice is given for an open file. 28320 POSIX_FADV_SEQUENTIAL 28321 Specifies that the application expects to access the specified data sequentially from lower 28322 offsets to higher offsets. 28323 POSIX_FADV_RANDOM 28324 Specifies that the application expects to access the specified data in a random order. 28325 POSIX_FADV_WILLNEED 28326 Specifies that the application expects to access the specified data in the near future. 28327 POSIX_FADV_DONTNEED 28328 Specifies that the application expects that it will not access the specified data in the near 28329 future. 28330 POSIX_FADV_NOREUSE 28331 Specifies that the application expects to access the specified data once and then not reuse it 28332 thereafter. 28333 These values shall be defined in . | 28334 RETURN VALUE 28335 Upon successful completion, posix_fadvise( ) shall return zero; otherwise, an error number shall 28336 be returned to indicate the error. 28337 ERRORS 28338 The posix_fadvise( ) function shall fail if: 28339 [EBADF] The fd argument is not a valid file descriptor. 28340 [EINVAL] The value of advice is invalid. | 28341 [ESPIPE] The fd argument is associated with a pipe or FIFO. 1380 Technical Standard (2000) (Draft July 31, 2000) System Interfaces posix_fadvise( ) 28342 EXAMPLES 28343 None. 28344 APPLICATION USAGE 28345 The posix_fadvise( ) function is part of the Advisory Information option and need not be provided | 28346 on all implementations. 28347 RATIONALE 28348 None. 28349 FUTURE DIRECTIONS 28350 None. 28351 SEE ALSO 28352 posix_madvise( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 28353 CHANGE HISTORY 28354 First released in Issue 6. Derived from IEEE Std. 1003.1d-1999. 28355 In the SYNOPSIS, the inclusion of is no longer required. System Interfaces, Issue 6 1381 posix_fallocate( ) System Interfaces 28356 NAME 28357 posix_fallocate - file space control 28358 SYNOPSIS 28359 ADV #include 28360 int posix_fallocate(int fd, off_t offset, size_t len); 28361 28362 DESCRIPTION 28363 The posix_fallocate( ) function ensures that any required storage for regular file data starting at 28364 offset and continuing for len bytes is allocated on the file system storage media. If posix_fallocate( ) 28365 returns successfully, subsequent writes to the specified file data shall not fail due to the lack of 28366 free space on the file system storage media. 28367 If the offset+len is beyond the current file size, then posix_fallocate( ) shall adjust the file size to 28368 offset+len. Otherwise, the file size shall not be changed. 28369 It is implementation-defined whether a previous posix_fadvise( ) call influences allocation | 28370 strategy. 28371 Space allocated via posix_fallocate( ) shall be freed by a successful call to creat( ) or open( ) that 28372 truncates the size of the file. Space allocated via posix_fallocate( ) may be freed by a successful call 28373 to ftruncate( ) that reduces the file size to a size smaller than offset+len. 28374 RETURN VALUE 28375 Upon successful completion, posix_fallocate( ) shall return zero; otherwise, an error number shall 28376 be returned to indicate the error. 28377 ERRORS 28378 The posix_fallocate( ) function shall fail if: 28379 [EBADF] The fd argument is not a valid file descriptor. 28380 [EBADF] The fd argument references a file that was opened without write permission. 28381 [EFBIG] The value of offset+len is greater than the maximum file size. 28382 [EINTR] A signal was caught during execution. 28383 [EINVAL] The len argument was zero or the offset argument was less than zero. 28384 [EIO] An I/O error occurred while reading from or writing to a file system. 28385 [ENODEV] The fd argument does not refer to a regular file. 28386 [ENOSPC] There is insufficient free space remaining on the file system storage media. 28387 [ESPIPE] The fd argument is associated with a pipe or FIFO. 28388 EXAMPLES 28389 None. 28390 APPLICATION USAGE 28391 The posix_fallocate( ) function is part of the Advisory Information option and need not be | 28392 provided on all implementations. 28393 RATIONALE 28394 None. 1382 Technical Standard (2000) (Draft July 31, 2000) System Interfaces posix_fallocate( ) 28395 FUTURE DIRECTIONS 28396 None. 28397 SEE ALSO 28398 creat( ), ftruncate( ), open( ), unlink( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 28399 28400 CHANGE HISTORY 28401 First released in Issue 6. Derived from IEEE Std. 1003.1d-1999. 28402 In the SYNOPSIS, the inclusion of is no longer required. System Interfaces, Issue 6 1383 posix_madvise( ) System Interfaces 28403 NAME 28404 posix_madvise - memory advisory information and alignment control 28405 SYNOPSIS 28406 ADV #include 28407 int posix_madvise(void *addr, size_t len, int advice); 28408 28409 DESCRIPTION | 28410 MF|SHM The posix_madvise( ) function need only be supported if either the Memory Mapped Files or the | 28411 Shared Memory Objects options are supported. | 28412 The posix_madvise( ) function provides advice to the implementation on the expected behavior of 28413 the application with respect to the data in the memory starting at address addr, and continuing 28414 for len bytes. The implementation may use this information to optimize handling of the specified 28415 data. The posix_madvise( ) function has no effect on the semantics of access to memory in the | 28416 specified range, although it may affect the performance of access. | 28417 The implementation may require that addr be a multiple of the page size, which is the value 28418 returned by sysconf( ) when the name value _SC_PAGESIZE is used. 28419 The advice to be applied to the memory range is specified by the advice parameter and may be 28420 one of the following values: 28421 POSIX_MADV_NORMAL 28422 Specifies that the application has no advice to give on its behavior with respect to the 28423 specified range. It is the default characteristic if no advice is given for a range of memory. 28424 POSIX_MADV_SEQUENTIAL 28425 Specifies that the application expects to access the specified range sequentially from lower 28426 addresses to higher addresses. 28427 POSIX_MADV_RANDOM 28428 Specifies that the application expects to access the specified range in a random order. 28429 POSIX_MADV_WILLNEED 28430 Specifies that the application expects to access the specified range in the near future. 28431 POSIX_MADV_DONTNEED 28432 Specifies that the application expects that it will not access the specified range in the near 28433 future. 28434 These values shall be defined in . | 28435 RETURN VALUE 28436 Upon successful completion, posix_madvise( ) shall return zero; otherwise, an error number shall 28437 be returned to indicate the error. 28438 ERRORS 28439 The posix_madvise( ) function shall fail if: 28440 [EINVAL] The value of advice is invalid. | 28441 [ENOMEM] Addresses in the range starting at addr and continuing for len bytes are partly 28442 or completely outside the range allowed for the address space of the calling 28443 process. 28444 The posix_madvise( ) function may fail if: 1384 Technical Standard (2000) (Draft July 31, 2000) System Interfaces posix_madvise( ) 28445 [EINVAL] The value of addr is not a multiple of the value returned by sysconf( ) when the 28446 name value _SC_PAGESIZE is used. 28447 [EINVAL] The value of len is zero. 28448 EXAMPLES 28449 None. 28450 APPLICATION USAGE 28451 The posix_madvise( ) function is part of the Advisory Information option and need not be | 28452 provided on all implementations. 28453 RATIONALE 28454 None. 28455 FUTURE DIRECTIONS 28456 None. 28457 SEE ALSO 28458 mmap( ), posix_fadvise( ), sysconf( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 28459 28460 CHANGE HISTORY 28461 First released in Issue 6. Derived from IEEE Std. 1003.1d-1999. 28462 IEEE PASC Interpretation 1003.1 #102 is included. | System Interfaces, Issue 6 1385 posix_mem_offset( ) System Interfaces 28463 NAME 28464 posix_mem_offset - find offset and length of a mapped typed memory block 28465 SYNOPSIS 28466 TYM #include 28467 int posix_mem_offset(const void *restrict addr, size_t len, | 28468 off_t *restrict off, size_t *restrict contig_len, | 28469 int *restrict fildes); | 28470 | 28471 DESCRIPTION 28472 The posix_mem_offset( ) function returns in the variable pointed to by off a value that identifies 28473 the offset (or location), within a memory object, of the memory block currently mapped at addr. 28474 The function shall return in the variable pointed to by fildes, the descriptor used (via mmap( )) to 28475 establish the mapping which contains addr. If that descriptor was closed since the mapping was 28476 established, the returned value of fildes shall be -1. The len argument specifies the length of the 28477 block of the memory object the user wishes the offset for; upon return, the value pointed to by 28478 contig_len shall equal either len, or the length of the largest contiguous block of the memory 28479 object that is currently mapped to the calling process starting at addr, whichever is smaller. 28480 If the memory object mapped at addr is a typed memory object, then if the off and contig_len 28481 values obtained by calling posix_mem_offset( ) are used in a call to mmap( ) with a file descriptor 28482 that refers to the same memory pool as fildes (either through the same port or through a different 28483 port), and that was opened with neither the POSIX_TYPED_MEM_ALLOCATE nor the 28484 POSIX_TYPED_MEM_ALLOCATE_CONTIG flag, the typed memory area that is mapped shall 28485 be exactly the same area that was mapped at addr in the address space of the process that called 28486 posix_mem_offset( ). 28487 If the memory object specified by fildes is not a typed memory object, then the behavior of this 28488 function is implementation-defined. | 28489 RETURN VALUE 28490 Upon successful completion, the posix_mem_offset( ) function shall return zero; otherwise, the 28491 corresponding error status value shall be returned. 28492 ERRORS 28493 The posix_mem_offset( ) function shall fail if: 28494 [EACCES] The process has not mapped a memory object supported by this function at 28495 the given address addr. 28496 This function shall not return an error code of [EINTR]. | 28497 EXAMPLES 28498 None. 28499 APPLICATION USAGE 28500 None. 28501 RATIONALE 28502 None. 28503 FUTURE DIRECTIONS 28504 None. 1386 Technical Standard (2000) (Draft July 31, 2000) System Interfaces posix_mem_offset( ) 28505 SEE ALSO 28506 mmap( ), posix_typed_mem_open( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 28507 28508 CHANGE HISTORY 28509 First released in Issue 6. Derived from IEEE Std. 1003.1j-2000. System Interfaces, Issue 6 1387 posix_memalign( ) System Interfaces 28510 NAME 28511 posix_memalign - aligned memory allocation 28512 SYNOPSIS 28513 ADV #include 28514 int posix_memalign(void **memptr, size_t alignment, size_t size); 28515 28516 DESCRIPTION 28517 The posix_memalign( ) function allocates size bytes aligned on a boundary specified by alignment, 28518 and returns a pointer to the allocated memory in memptr. The value of alignment shall be a | 28519 multiple of sizeof(void*), that is also a power of two. Upon successful completion, the value | 28520 pointed to by memptr shall be a multiple of alignment. 28521 CX The free( ) function shall deallocate memory that has previously been allocated by | 28522 posix_memalign( ). 28523 RETURN VALUE 28524 Upon successful completion, posix_memalign( ) shall return zero; otherwise, an error number 28525 shall be returned to indicate the error. 28526 ERRORS 28527 The posix_memalign( ) function shall fail if: 28528 [EINVAL] The value of the alignment parameter is not a power of two multiple of 28529 sizeof(void*). 28530 [ENOMEM] There is insufficient memory available with the requested alignment. 28531 EXAMPLES 28532 None. 28533 APPLICATION USAGE 28534 The posix_memalign( ) function is part of the Advisory Information option and need not be | 28535 provided on all implementations. 28536 RATIONALE 28537 None. 28538 FUTURE DIRECTIONS 28539 None. 28540 SEE ALSO 28541 free( ), malloc( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 28542 CHANGE HISTORY 28543 First released in Issue 6. Derived from IEEE Std. 1003.1d-1999. 28544 In the SYNOPSIS, the inclusion of is no longer required. 1388 Technical Standard (2000) (Draft July 31, 2000) System Interfaces posix_spawn( ) 28545 NAME 28546 posix_spawn, posix_spawnp - spawn a process (REALTIME) 28547 SYNOPSIS 28548 SPN #include 28549 int posix_spawn(pid_t *restrict pid, const char *restrict path, | 28550 const posix_spawn_file_actions_t *file_actions, | 28551 const posix_spawnattr_t *restrict attrp, | 28552 char *restrict const argv[restrict], | 28553 char *restrict const envp[restrict]); | 28554 int posix_spawnp(pid_t *restrict pid, const char *restrict file, | 28555 const posix_spawn_file_actions_t *file_actions, | 28556 const posix_spawnattr_t *restrict attrp, char *const argv[restrict], | 28557 char * const envp[restrict]); | 28558 | 28559 DESCRIPTION 28560 The posix_spawn( ) and posix_spawnp( ) functions shall create a new process (child process) from 28561 the specified process image. The new process image is constructed from a regular executable file 28562 called the new process image file. 28563 When a C program is executed as the result of this call, it shall be entered as a C language 28564 function call as follows: 28565 int main(int argc, char *argv[]); 28566 where argc is the argument count and argv is an array of character pointers to the arguments 28567 themselves. In addition, the following variable: 28568 extern char **environ; 28569 is initialized as a pointer to an array of character pointers to the environment strings. 28570 The argument argv is an array of character pointers to null-terminated strings. The last member | 28571 of this array shall be a null pointer and is not counted in argc. These strings constitute the | 28572 argument list available to the new process image. The value in argv[0] should point to a file 28573 name that is associated with the process image being started by the posix_spawn( ) or 28574 posix_spawnp( ) function. 28575 The argument envp is an array of character pointers to null-terminated strings. These strings 28576 constitute the environment for the new process image. The environment array is terminated by a 28577 null pointer. 28578 The number of bytes available for the child process' combined argument and environment lists 28579 is {ARG_MAX}. The implementation shall specify in the system documentation (see the Base | 28580 Definitions volume of IEEE Std. 1003.1-200x, Chapter 2, Conformance) whether any list | 28581 overhead, such as length words, null terminators, pointers, or alignment bytes, is included in | 28582 this total. 28583 The path argument to posix_spawn( ) is a path name that identifies the new process image file to 28584 execute. 28585 The file parameter to posix_spawnp( ) shall be used to construct a path name that identifies the 28586 new process image file. If the file parameter contains a slash character, the file parameter shall be 28587 used as the path name for the new process image file. Otherwise, the path prefix for this file shall 28588 be obtained by a search of the directories passed as the environment variable PATH (see the Base | 28589 Definitions volume of IEEE Std. 1003.1-200x, Chapter 8, Environment Variables). If this | 28590 environment variable is not defined, the results of the search are implementation-defined. | System Interfaces, Issue 6 1389 posix_spawn( ) System Interfaces 28591 If file_actions is a null pointer, then file descriptors open in the calling process shall remain open 28592 in the child process, except for those whose close-on-exec flag FD_CLOEXEC is set (see fcntl( )). 28593 For those file descriptors that remain open, all attributes of the corresponding open file 28594 descriptions, including file locks (see fcntl( )), shall remain unchanged. 28595 If file_actions is not NULL, then the file descriptors open in the child process shall be those open 28596 in the calling process as modified by the spawn file actions object pointed to by file_actions and 28597 the FD_CLOEXEC flag of each remaining open file descriptor after the spawn file actions have 28598 been processed. The effective order of processing the spawn file actions shall be: 28599 1. The set of open file descriptors for the child process shall initially be the same set as is 28600 open for the calling process. All attributes of the corresponding open file descriptions, 28601 including file locks (see fcntl( )), shall remain unchanged. 28602 2. The signal mask, signal default actions, and the effective user and group IDs for the child | 28603 process shall be changed as specified in the attributes object referenced by attrp. | 28604 3. The file actions specified by the spawn file actions object shall be performed in the order in 28605 which they were added to the spawn file actions object. 28606 4. Any file descriptor that has its FD_CLOEXEC flag set (see fcntl( )) shall be closed. | 28607 The posix_spawnattr_t spawn attributes object type is defined in . It shall contain at 28608 least the attributes defined below. 28609 If the POSIX_SPAWN_SETPGROUP flag is set in the spawn-flags attribute of the object 28610 referenced by attrp, and the spawn-pgroup attribute of the same object is non-zero, then the 28611 child's process group shall be as specified in the spawn-pgroup attribute of the object referenced 28612 by attrp. 28613 As a special case, if the POSIX_SPAWN_SETPGROUP flag is set in the spawn-flags attribute of 28614 the object referenced by attrp, and the spawn-pgroup attribute of the same object is set to zero, | 28615 then the child shall be in a new process group with a process group ID equal to its process ID. | 28616 If the POSIX_SPAWN_SETPGROUP flag is not set in the spawn-flags attribute of the object 28617 referenced by attrp, the new child process shall inherit the parent's process group. 28618 PS If the POSIX_SPAWN_SETSCHEDPARAM flag is set in the spawn-flags attribute of the object | 28619 referenced by attrp, but POSIX_SPAWN_SETSCHEDULER is not set, the new process image 28620 shall initially have the scheduling policy of the calling process with the scheduling parameters 28621 specified in the spawn-schedparam attribute of the object referenced by attrp. 28622 If the POSIX_SPAWN_SETSCHEDULER flag is set in spawn-flags attribute of the object | 28623 referenced by attrp (regardless of the setting of the POSIX_SPAWN_SETSCHEDPARAM flag), 28624 the new process image shall initially have the scheduling policy specified in the spawn- 28625 schedpolicy attribute of the object referenced by attrp and the scheduling parameters specified in 28626 the spawn-schedparam attribute of the same object. | 28627 The POSIX_SPAWN_RESETIDS flag in the spawn-flags attribute of the object referenced by attrp 28628 governs the effective user ID of the child process. If this flag is not set, the child process inherits 28629 the parent process' effective user ID. If this flag is set, the child process' effective user ID is reset 28630 to the parent's real user ID. In either case, if the set-user-ID mode bit of the new process image 28631 file is set, the effective user ID of the child process will become that file's owner ID before the 28632 new process image begins execution. 28633 The POSIX_SPAWN_RESETIDS flag in the spawn-flags attribute of the object referenced by attrp 28634 also governs the effective group ID of the child process. If this flag is not set, the child process 28635 inherits the parent process' effective group ID. If this flag is set, the child process' effective group 28636 ID is reset to the parent's real group ID. In either case, if the set-group-ID mode bit of the new 1390 Technical Standard (2000) (Draft July 31, 2000) System Interfaces posix_spawn( ) 28637 process image file is set, the effective group ID of the child process will become that file's group 28638 ID before the new process image begins execution. 28639 If the POSIX_SPAWN_SETSIGMASK flag is set in the spawn-flags attribute of the object 28640 referenced by attrp, the child process shall initially have the signal mask specified in the spawn- 28641 sigmask attribute of the object referenced by attrp. 28642 If the POSIX_SPAWN_SETSIGDEF flag is set in the spawn-flags attribute of the object referenced 28643 by attrp, the signals specified in the spawn-sigdefault attribute of the same object shall be set to 28644 their default actions in the child process. Signals set to the default action in the parent process 28645 shall be set to the default action in the child process. 28646 Signals set to be caught by the calling process shall be set to the default action in the child 28647 process. 28648 Signals set to be ignored by the calling process image shall be set to be ignored by the child 28649 process, unless otherwise specified by the POSIX_SPAWN_SETSIGDEF flag being set in the 28650 spawn-flags attribute of the object referenced by attrp and the signals being indicated in the 28651 spawn-sigdefault attribute of the object referenced by attrp. 28652 If the value of the attrp pointer is NULL, then the default values are used. 28653 All process attributes, other than those influenced by the attributes set in the object referenced 28654 by attrp as specified above or by the file descriptor manipulations specified in file_actions , shall 28655 appear in the new process image as though fork( ) had been called to create a child process and 28656 then a member of the exec family of functions had been called by the child process to execute the 28657 new process image. 28658 THR It is implementation-defined whether the fork handlers are run when posix_spawn( ) or | 28659 posix_spawnp( ) is called. | 28660 RETURN VALUE 28661 Upon successful completion, posix_spawn( ) and posix_spawnp( ) shall return the process ID of the 28662 child process to the parent process, in the variable pointed to by a non-NULL pid argument, and 28663 shall return zero as the function return value. Otherwise, no child process shall be created, the 28664 value stored into the variable pointed to by a non-NULL pid is unspecified, and an error number 28665 shall be returned as the function return value to indicate the error. If the pid argument is a null 28666 pointer, the process ID of the child is not returned to the caller. 28667 ERRORS 28668 The posix_spawn( ) and posix_spawnp( ) functions may fail if: 28669 [EINVAL] The value specified by file_actions or attrp is invalid. 28670 If this error occurs after the calling process successfully returns from the posix_spawn( ) or 28671 posix_spawnp( ) function, the child process may exit with exit status 127. 28672 If posix_spawn( ) or posix_spawnp( ) fail for any of the reasons that would cause fork( ) or one of 28673 the exec family of functions to fail, an error value shall be returned as described by fork( ) and | 28674 exec, respectively (or, if the error occurs after the calling process successfully returns, the child | 28675 process exits with exit status 127). | 28676 If POSIX_SPAWN_SETPGROUP is set in the spawn-flags attribute of the object referenced by 28677 attrp, and posix_spawn( ) or posix_spawnp( ) fails while changing the child's process group, an 28678 error value shall be returned as described by setpgid( ) (or, if the error occurs after the calling | 28679 process successfully returns, the child process exits with exit status 127). | 28680 PS If POSIX_SPAWN_SETSCHEDPARAM is set and POSIX_SPAWN_SETSCHEDULER is not set | 28681 in the spawn-flags attribute of the object referenced by attrp, then if posix_spawn( ) or | System Interfaces, Issue 6 1391 posix_spawn( ) System Interfaces 28682 posix_spawnp( ) fails for any of the reasons that would cause sched_setparam( ) to fail, an error | 28683 value shall be returned as described by sched_setparam( ) (or, if the error occurs after the calling | 28684 process successfully returns, the child process exits with exit status 127). | 28685 If POSIX_SPAWN_SETSCHEDULER is set in the spawn-flags attribute of the object referenced by | 28686 attrp, and if posix_spawn( ) or posix_spawnp( ) fails for any of the reasons that would cause | 28687 sched_setscheduler( ) to fail, an error value shall be returned as described by sched_setscheduler( ) | 28688 (or, if the error occurs after the calling process successfully returns, the child process exits with | 28689 exit status 127)> | 28690 If the file_actions argument is not NULL, and specifies any close, dup2, or open actions to be | 28691 performed, and if posix_spawn( ) or posix_spawnp( ) fails for any of the reasons that would cause | 28692 close( ), dup2( ), or open( ) to fail, an error value shall be returned as described by close( ), dup2( ), | 28693 and open( ), respectively (or, if the error occurs after the calling process successfully returns, the | 28694 child process exits with exit status 127). An open file action may, by itself, result in any of the | 28695 errors described by close( ) or dup2( ), in addition to those described by open( ). | 28696 EXAMPLES 28697 None. | 28698 APPLICATION USAGE 28699 These functions are part of the Spawn option and need not be provided on all implementations. | 28700 RATIONALE 28701 The POSIX fork( ) function is difficult or impossible to implement without swapping or dynamic 28702 address translation for the following reasons: 28703 * Swapping is generally too slow for a realtime environment. 28704 * Dynamic address translation is not available everywhere POSIX might be useful. 28705 * Processes are too useful to simply option out of POSIX whenever it must run without 28706 address translation or other MMU services, 28707 POSIX needs process creation and file execution primitives that can be efficiently implemented 28708 without address translation or other MMU services. 28709 This function shall be called posix_spawn( ). A closely related function, posix_spawnp( ), is 28710 included for completeness. 28711 The posix_spawn( ) function is implementable as a library routine, but both posix_spawn( ) and 28712 posix_spawnp( ) are designed as kernel operations. Also, although they may be an efficient 28713 replacement for many fork( )/exec pairs, their goal is to provide useful process creation 28714 primitives for systems that have difficulty with fork( ), not to provide drop-in replacements for 28715 fork( )/exec. 28716 This view of the role of posix_spawn( ) and posix_spawnp( ) influenced the design of their API. It 28717 does not attempt to provide the full functionality of fork( )/exec in which arbitrary user-specified 28718 operations of any sort are permitted between the creation of the child process and the execution 28719 of the new process image; any attempt to reach that level would need to provide a programming 28720 language as parameters. Instead, posix_spawn( ) and posix_spawnp( ) are process creation 28721 primitives like the Start_Process and Start_Process_Search Ada language bindings package 28722 POSIX_Process_Primitives and also like those in many operating systems that are not UNIX 28723 systems, but with some POSIX-specific additions. 28724 To achieve its coverage goals, posix_spawn( ) and posix_spawnp( ) have control of six types of 28725 inheritance: file descriptors, process group ID, user and group ID, signal mask, scheduling, and 28726 whether each signal ignored in the parent will remain ignored in the child, or be reset to its 28727 default action in the child. 1392 Technical Standard (2000) (Draft July 31, 2000) System Interfaces posix_spawn( ) 28728 Control of file descriptors is required to allow an independently written child process image to 28729 access data streams opened by and even generated or read by the parent process without being 28730 specifically coded to know which parent files and file descriptors are to be used. Control of the 28731 process group ID is required to control how the child process' job control relates to that of the 28732 parent. 28733 Control of the signal mask and signal defaulting is sufficient to support the implementation of 28734 system( ). Although support for system( ) is not explicitly one of the goals for posix_spawn( ) and 28735 posix_spawnp( ), it is covered under the ``at least 50%'' coverage goal. 28736 The intention is that the normal file descriptor inheritance across fork( ), the subsequent effect of 28737 the specified spawn file actions, and the normal file descriptor inheritance across one of the exec 28738 family of functions should fully specify open file inheritance. The implementation need make no 28739 decisions regarding the set of open file descriptors when the child process image begins 28740 execution, those decisions having already been made by the caller and expressed as the set of 28741 open file descriptors and their FD_CLOEXEC flags at the time of the call and the spawn file 28742 actions object specified in the call. We have been assured that in cases where the POSIX 28743 Start_Process Ada primitives have been implemented in a library, this method of controlling file 28744 descriptor inheritance may be implemented very easily. 28745 We can identify several problems with posix_spawn( ) and posix_spawnp( ), but there does not 28746 appear to be a solution that introduces fewer problems. Environment modification for child 28747 process attributes not specifiable via the attrp or file_actions arguments must be done in the 28748 parent process, and since the parent generally wants to save its context, it is more costly than 28749 similar functionality with fork( )/exec. It is also complicated to modify the environment of a 28750 multi-threaded process temporarily, since all threads must agree when it is safe for the 28751 environment to be changed. However, this cost is only borne by those invocations of 28752 posix_spawn( ) and posix_spawnp( ) that use the additional functionality. Since extensive 28753 modifications are not the usual case, and are particularly unlikely in time-critical code, keeping 28754 much of the environment control out of posix_spawn( ) and posix_spawnp( ) is appropriate design. 28755 The posix_spawn( ) and posix_spawnp( ) functions do not have all the power of fork( )/exec. This is 28756 to be expected. The fork( ) function is a wonderfully powerful operation. We do not expect to 28757 duplicate its functionality in a simple, fast function with no special hardware requirements. It is 28758 worth noting that posix_spawn( ) and posix_spawnp( ) are very similar to the process creation 28759 operations on many operating systems that are not UNIX systems. 28760 Requirements 28761 The requirements for posix_spawn( ) and posix_spawnp( ) are: 28762 * They must be implementable without an MMU or unusual hardware. 28763 * They must be compatible with existing POSIX standards. 28764 Additional goals are: 28765 * They should be efficiently implementable. 28766 * They should be able to replace at least 50% of typical executions of fork( ). 28767 * A system with posix_spawn( ) and posix_spawnp( ) and without fork( ) should be useful, at least 28768 for realtime applications. 28769 * A system with fork( ) and the exec family should be able to implement posix_spawn( ) and 28770 posix_spawnp( ) as library routines. System Interfaces, Issue 6 1393 posix_spawn( ) System Interfaces 28771 Two-Syntax 28772 POSIX exec has several calling sequences with approximately the same functionality. These 28773 appear to be required for compatibility with existing practice. Since the existing practice for the 28774 posix_spawn*( ) functions is otherwise substantially unlike POSIX, we feel that simplicity 28775 outweighs compatibility. There are, therefore, only two names for the posix_spawn*( ) functions. 28776 The parameter list does not differ between posix_spawn( ) and posix_spawnp( ); posix_spawnp( ) 28777 interprets the second parameter more elaborately than posix_spawn( ). | 28778 Compatibility with POSIX.5 (Ada) | 28779 The Start_Process and Start_Process_Search procedures from the POSIX_Process_Primitives | 28780 package from the Ada language binding to POSIX.1 encapsulate fork( ) and exec functionality in a | 28781 manner similar to that of posix_spawn( ) and posix_spawnp( ). Originally, in keeping with our 28782 simplicity goal, the standard developers had limited the capabilities of posix_spawn( ) and 28783 posix_spawnp( ) to a subset of the capabilities of Start_Process and Start_Process_Search; certain 28784 non-default capabilities were not supported. However, based on suggestions by the ballot group 28785 to improve file descriptor mapping or drop it, and on the advice of an Ada Language Bindings 28786 working group member, the standard developers decided that posix_spawn( ) and posix_spawnp( ) 28787 should be sufficiently powerful to implement Start_Process and Start_Process_Search. The 28788 rationale is that if the Ada language binding to such a primitive had already been approved as 28789 an IEEE standard, there can be little justification for not approving the functionally-equivalent 28790 parts of a C binding. The only three capabilities provided by posix_spawn( ) and posix_spawnp( ) 28791 that are not provided by Start_Process and Start_Process_Search are optionally specifying the 28792 child's process group ID, the set of signals to be reset to default signal handling in the child 28793 process, and the child's scheduling policy and parameters. 28794 For the Ada language binding for Start_Process to be implemented with posix_spawn( ), that 28795 binding would need to explicitly pass an empty signal mask and the parent's environment to 28796 posix_spawn( ) whenever the caller of Start_Process allowed these arguments to default, since 28797 posix_spawn( ) does not provide such defaults. The ability of Start_Process to mask user-specified 28798 signals during its execution is functionally unique to the Ada language binding and must be 28799 dealt with in the binding separately from the call to posix_spawn( ). 28800 Process Group 28801 The process group inheritance field can be used to join the child process with an existing process 28802 group. By assigning a value of zero to the spawn-pgroup attribute of the object referenced by 28803 attrp, the setpgid( ) mechanism will place the child process in a new process group. 28804 Threads 28805 Without the posix_spawn( ) and posix_spawnp( ) functions, systems without address translation 28806 can still use threads to give an abstraction of concurrency. In many cases, thread creation 28807 suffices, but it is not always a good substitute. The posix_spawn( ) and posix_spawnp( ) functions 28808 are considerably ``heavier'' than thread creation. Processes have several important attributes that 28809 threads do not. Even without address translation, a process may have base-and-bound memory 28810 protection. Each process has a process environment including security attributes and file 28811 capabilities, and powerful scheduling attributes. Processes abstract the behavior of non- 28812 uniform-memory-architecture multi-processors better than threads, and they are more 28813 convenient to use for activities that are not closely linked. 28814 The posix_spawn( ) and posix_spawnp( ) functions may not bring support for multiple processes to 28815 every configuration. Process creation is not the only piece of operating system support required 28816 to support multiple processes. The total cost of support for multiple processes may be quite high 1394 Technical Standard (2000) (Draft July 31, 2000) System Interfaces posix_spawn( ) 28817 in some circumstances. Existing practice shows that support for multiple processes is 28818 uncommon and threads are common among ``tiny kernels''. There should, therefore, probably 28819 continue to be AEPs for operating systems with only one process. 28820 Asynchronous Error Notification 28821 A library implementation of posix_spawn( ) or posix_spawnp( ) may not be able to detect all 28822 possible errors before it forks the child process. IEEE Std. 1003.1-200x provides for an error 28823 indication returned from a child process which could not successfully complete the spawn 28824 operation via a special exit status which may be detected using the status value returned by 28825 wait( ) and waitpid( ). 28826 The stat_val interface and the macros used to interpret it are not well suited to the purpose of 28827 returning API errors, but they are the only path available to a library implementation. Thus, an 28828 implementation may cause the child process to exit with exit status 127 for any error detected 28829 during the spawn process after the posix_spawn( ) or posix_spawnp( ) function has successfully 28830 returned. 28831 The standard developers had proposed using two additional macros to interpret stat_val. The 28832 first, WIFSPAWNFAIL, would have detected a status that indicated that the child exited because 28833 of an error detected during the posix_spawn( ) or posix_spawnp( ) operations rather than during 28834 actual execution of the child process image; the second, WSPAWNERRNO, would have 28835 extracted the error value if WIFSPAWNFAIL indicated a failure. Unfortunately, the ballot group 28836 strongly opposed this because it would make a library implementation of posix_spawn( ) or 28837 posix_spawnp( ) dependent on kernel modifications to waitpid( ) to be able to embed special 28838 information in stat_val to indicate a spawn failure. 28839 The 8 bits of child process exit status that are guaranteed by IEEE Std. 1003.1-200x to be 28840 accessible to the waiting parent process are insufficient to disambiguate a spawn error from any | 28841 other kind of error that may be returned by an arbitrary process image. No other bits of the exit | 28842 status are required to be visible in stat_val, so these macros could not be strictly implemented at 28843 the library level. Reserving an exit status of 127 for such spawn errors is consistent with the use 28844 of this value by system( ) and popen( ) to signal failures in these operations that occur after the 28845 function has returned but before a shell is able to execute. The exit status of 127 does not 28846 uniquely identify this class of error, nor does it provide any detailed information on the nature 28847 of the failure. Note that a kernel implementation of posix_spawn( ) or posix_spawnp( ) is permitted 28848 (and encouraged) to return any possible error as the function value, thus providing more 28849 detailed failure information to the parent process. 28850 Thus, no special macros are available to isolate asynchronous posix_spawn( ) or posix_spawnp( ) 28851 errors. Instead, errors detected by the posix_spawn( ) or posix_spawnp( ) operations in the context 28852 of the child process before the new process image executes are reported by setting the child's 28853 exit status to 127. The calling process may use the WIFEXITED and WEXITSTATUS macros on 28854 the stat_val stored by the wait( ) or waitpid( ) functions to detect spawn failures to the extent that 28855 other status values with which the child process image may exit (before the parent can 28856 conclusively determine that the child process image has begun execution) are distinct from exit 28857 status 127. 28858 FUTURE DIRECTIONS 28859 None. 28860 SEE ALSO 28861 alarm( ), chmod( ), close( ), dup( ), exec, exit( ), fcntl( ), fork( ), kill( ), open( ), | 28862 posix_spawn_file_actions_addclose( ), posix_spawn_file_actions_adddup2( ), 28863 posix_spawn_file_actions_addopen( ), posix_spawn_file_actions_destroy( ), 28864 posix_spawn_file_actions_init( ), posix_spawnattr_destroy( ), posix_spawnattr_init( ), | System Interfaces, Issue 6 1395 posix_spawn( ) System Interfaces 28865 posix_spawnattr_getsigdefault( ), posix_spawnattr_getflags( ), posix_spawnattr_getpgroup( ), | 28866 posix_spawnattr_getschedparam( ), posix_spawnattr_getschedpolicy( ), posix_spawnattr_getsigmask( ), | 28867 posix_spawnattr_setsigdefault( ), posix_spawnattr_setflags( ), posix_spawnattr_setpgroup( ), | 28868 posix_spawnattr_setschedparam( ), posix_spawnattr_setschedpolicy( ), posix_spawnattr_setsigmask( ), 28869 sched_setparam( ), sched_setscheduler( ), setpgid( ), setuid( ), stat( ), times( ), wait( ), the Base | 28870 Definitions volume of IEEE Std. 1003.1-200x, | 28871 CHANGE HISTORY 28872 First released in Issue 6. Derived from IEEE Std. 1003.1d-1999. 28873 IEEE PASC Interpretation 1003.1 #103 is included, noting that the signal default actions are | 28874 changed as well as the signal mask in step 2. | 1396 Technical Standard (2000) (Draft July 31, 2000) System Interfaces posix_spawn_file_actions_addclose( ) 28875 NAME 28876 posix_spawn_file_actions_addclose, posix_spawn_file_actions_addopen - add close or open | 28877 action to spawn file actions object (REALTIME) | 28878 SYNOPSIS 28879 SPN #include 28880 int posix_spawn_file_actions_addclose(posix_spawn_file_actions_t * 28881 file_actions, int fildes); 28882 int posix_spawn_file_actions_addopen(posix_spawn_file_actions_t *restrict| 28883 file_actions, int fildes, const char *restrict path, | 28884 int oflag, mode_t mode); | 28885 | 28886 DESCRIPTION 28887 A spawn file actions object is of type posix_spawn_file_actions_t (defined in ) and is 28888 used to specify a series of actions to be performed by a posix_spawn( ) or posix_spawnp( ) 28889 operation in order to arrive at the set of open file descriptors for the child process given the set of 28890 open file descriptors of the parent. IEEE Std. 1003.1-200x does not define comparison or 28891 assignment operators for the type posix_spawn_file_actions_t. 28892 A spawn file actions object, when passed to posix_spawn( ) or posix_spawnp( ), shall specify how 28893 the set of open file descriptors in the calling process is transformed into a set of potentially open 28894 file descriptors for the spawned process. This transformation shall be as if the specified sequence 28895 of actions was performed exactly once, in the context of the spawned process (prior to execution 28896 of the new process image), in the order in which the actions were added to the object; 28897 additionally, when the new process image is executed, any file descriptor (from this new set) 28898 which has its FD_CLOEXEC flag set will be closed (see posix_spawn( )). 28899 The posix_spawn_file_actions_addclose( ) function adds a close action to the object referenced by 28900 file_actions that will cause the file descriptor fildes to be closed (as if close(fildes) had been called) 28901 when a new process is spawned using this file actions object. 28902 The posix_spawn_file_actions_addopen( ) function adds an open action to the object referenced by 28903 file_actions that will cause the file named by path to be opened (as if open(path, oflag, mode) had 28904 been called, and the returned file descriptor, if not fildes, had been changed to fildes) when a new 28905 process is spawned using this file actions object. If fildes was already an open file descriptor, it 28906 shall be closed before the new file is opened. | 28907 Notes to Reviewers | 28908 This section with side shading will not appear in the final copy. - Ed. | 28909 D3, XSH, ERN 448 says the description of the posix_spawn_file_actions_addopen function does | 28910 not say whether the function has to make a copy of the path parameter or whether it can store | 28911 the pointer and assume the application does not destroy the copy of the string. Add to the | 28912 description: "The string pointed to by path can become invalid so the function has to make a | 28913 copy." | 28914 RETURN VALUE | 28915 Upon successful completion, these functions shall return zero; otherwise, an error number shall | 28916 be returned to indicate the error. 28917 ERRORS 28918 These functions shall fail if: 28919 [EBADF] The value specified by fildes is negative or greater than or equal to 28920 {OPEN_MAX}. System Interfaces, Issue 6 1397 posix_spawn_file_actions_addclose( ) System Interfaces 28921 These functions may fail if: 28922 [EINVAL] The value specified by file_actions is invalid. 28923 [ENOMEM] Insufficient memory exists to add to the spawn file actions object. 28924 It shall not be considered an error for the fildes argument passed to these functions to specify a 28925 file descriptor for which the specified operation could not be performed at the time of the call. 28926 Any such error will be detected when the associated file actions object is later used during a 28927 posix_spawn( ) or posix_spawnp( ) operation. 28928 EXAMPLES 28929 None. 28930 APPLICATION USAGE 28931 These functions are part of the Spawn option and need not be provided on all implementations. | 28932 RATIONALE 28933 A spawn file actions object may be initialized to contain an ordered sequence of close( ), dup2( ), 28934 and open( ) operations to be used by posix_spawn( ) or posix_spawnp( ) to arrive at the set of open 28935 file descriptors inherited by the spawned process from the set of open file descriptors in the 28936 parent at the time of the posix_spawn( ) or posix_spawnp( ) call. It had been suggested that the 28937 close( ) and dup2( ) operations alone are sufficient to rearrange file descriptors, and that files 28938 which need to be opened for use by the spawned process can be handled either by having the 28939 calling process open them before the posix_spawn( ) or posix_spawnp( ) call (and close them after), 28940 or by passing file names to the spawned process (in argv) so that it may open them itself. The 28941 standard developers recommend that applications use one of these two methods when practical, 28942 since detailed error status on a failed open operation is always available to the application this 28943 way. However, the standard developers feel that allowing a spawn file actions object to specify 28944 open operations is still appropriate because: 28945 1. It is consistent with equivalent POSIX.5 (Ada) functionality. 28946 2. It supports the I/O redirection paradigm commonly employed by POSIX programs 28947 designed to be invoked from a shell. When such a program is the child process, it may not 28948 be designed to open files on its own. 28949 3. It allows file opens that might otherwise fail or violate file ownership/access rights if 28950 executed by the parent process. 28951 Regarding 2. above, note that the spawn open file action provides to posix_spawn( ) and 28952 posix_spawnp( ) the same capability that the shell redirection operators provide to system( ), only 28953 without the intervening execution of a shell; for example: 28954 system ("myprog | 28986 CHANGE HISTORY 28987 First released in Issue 6. Derived from IEEE Std. 1003.1d-1999. | System Interfaces, Issue 6 1399 posix_spawn_file_actions_adddup2( ) System Interfaces 28988 NAME 28989 posix_spawn_file_actions_adddup2 - add dup2 action to spawn file actions object | 28990 (REALTIME) | 28991 SYNOPSIS 28992 SPN #include 28993 int posix_spawn_file_actions_adddup2(posix_spawn_file_actions_t * 28994 file_actions, int fildes, int newfildes); 28995 28996 DESCRIPTION 28997 A spawn file actions object is as defined in posix_spawn_file_actions_addclose( ). 28998 The posix_spawn_file_actions_adddup2( ) function adds a dup2( ) action to the object referenced by 28999 file_actions that will cause the file descriptor fildes to be duplicated as newfildes (as if dup2(fildes, 29000 newfildes) had been called) when a new process is spawned using this file actions object. | 29001 RETURN VALUE | 29002 Upon successful completion, the posix_spawn_file_actions_adddup2( ) function shall return zero; | 29003 otherwise, an error number shall be returned to indicate the error. 29004 ERRORS 29005 The posix_spawn_file_actions_adddup2( ) function shall fail if: 29006 [EBADF] The value specified by fildes or newfildes is negative or greater than or equal to | 29007 {OPEN_MAX}. 29008 [ENOMEM] Insufficient memory exists to add to the spawn file actions object. 29009 The posix_spawn_file_actions_adddup2( ) function may fail if: 29010 [EINVAL] The value specified by file_actions is invalid. 29011 It shall not be considered an error for the fildes argument passed to the 29012 posix_spawn_file_actions_adddup2( ) function to specify a file descriptor for which the specified 29013 operation could not be performed at the time of the call. Any such error will be detected when 29014 the associated file actions object is later used during a posix_spawn( ) or posix_spawnp( ) 29015 operation. 29016 EXAMPLES 29017 None. 29018 APPLICATION USAGE 29019 The posix_spawn_file_actions_adddup2( ) function is part of the Spawn option and need not be | 29020 provided on all implementations. 29021 RATIONALE 29022 Refer to the RATIONALE in posix_spawn_file_actions_addclose( ). 29023 FUTURE DIRECTIONS 29024 None. 29025 SEE ALSO 29026 dup( ), posix_spawn( ), posix_spawn_file_actions_addclose( ), posix_spawn_file_actions_destroy( ), 29027 posix_spawnp( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 1400 Technical Standard (2000) (Draft July 31, 2000) System Interfaces posix_spawn_file_actions_adddup2( ) 29028 CHANGE HISTORY 29029 First released in Issue 6. Derived from IEEE Std. 1003.1d-1999. 29030 IEEE PASC Interpretation 1003.1 #104 is included, noting that the [EBADF] error can apply to the | 29031 newfildes argument in addition to fildes. | System Interfaces, Issue 6 1401 posix_spawn_file_actions_addopen( ) System Interfaces 29032 NAME 29033 posix_spawn_file_actions_addopen - add open action to spawn file actions object | 29034 (REALTIME) | 29035 SYNOPSIS 29036 SPN #include 29037 int posix_spawn_file_actions_addopen(posix_spawn_file_actions_t *restrict| 29038 file_actions, int fildes, const char *restrict path, | 29039 int oflag, mode_t mode); | 29040 | 29041 DESCRIPTION 29042 Refer to posix_spawn_file_actions_addclose( ). 1402 Technical Standard (2000) (Draft July 31, 2000) System Interfaces posix_spawn_file_actions_destroy( ) 29043 NAME 29044 posix_spawn_file_actions_destroy, posix_spawn_file_actions_init - destroy and initialize 29045 spawn file actions object (REALTIME) 29046 SYNOPSIS 29047 SPN #include 29048 int posix_spawn_file_actions_destroy(posix_spawn_file_actions_t * 29049 file_actions); 29050 int posix_spawn_file_actions_init(posix_spawn_file_actions_t * 29051 file_actions); 29052 29053 DESCRIPTION 29054 A spawn file actions object is as defined in posix_spawn_file_actions_addclose( ). 29055 The posix_spawn_file_actions_destroy( ) function destroys the object referenced by file_actions ; the 29056 object becomes, in effect, uninitialized. An implementation may cause 29057 posix_spawn_file_actions_destroy( ) to set the object referenced by file_actions to an invalid value. A 29058 destroyed spawn file actions object can be reinitialized using posix_spawn_file_actions_init( ); the 29059 results of otherwise referencing the object after it has been destroyed are undefined. 29060 The posix_spawn_file_actions_init( ) function initializes the object referenced by file_actions to 29061 contain no file actions for posix_spawn( ) or posix_spawnp( ) to perform. | 29062 The effect of initializing an already initialized spawn file actions object is undefined. | 29063 RETURN VALUE | 29064 Upon successful completion, these functions shall return zero; otherwise, an error number shall | 29065 be returned to indicate the error. 29066 ERRORS 29067 The posix_spawn_file_actions_init( ) function shall fail if: 29068 [ENOMEM] Insufficient memory exists to initialize the spawn file actions object. 29069 The posix_spawn_file_actions_destroy( ) function may fail if: 29070 [EINVAL] The value specified by file_actions is invalid. 29071 EXAMPLES 29072 None. 29073 APPLICATION USAGE 29074 These functions are part of the Spawn option and need not be provided on all implementations. | 29075 RATIONALE 29076 Refer to the RATIONALE in posix_spawn_file_actions_addclose( ). 29077 FUTURE DIRECTIONS 29078 None. 29079 SEE ALSO 29080 posix_spawn( ), posix_spawnp( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 29081 CHANGE HISTORY 29082 First released in Issue 6. Derived from IEEE Std. 1003.1d-1999. 29083 In the SYNOPSIS, the inclusion of is no longer required. System Interfaces, Issue 6 1403 posix_spawn_file_actions_init( ) System Interfaces 29084 NAME 29085 posix_spawn_file_actions_init - initialize spawn file actions object (REALTIME) 29086 SYNOPSIS 29087 SPN #include 29088 int posix_spawn_file_actions_init(posix_spawn_file_actions_t * 29089 file_actions); 29090 29091 DESCRIPTION 29092 Refer to posix_spawn_file_actions_destroy( ). 1404 Technical Standard (2000) (Draft July 31, 2000) System Interfaces posix_spawnattr_destroy( ) 29093 NAME 29094 posix_spawnattr_destroy, posix_spawnattr_init - destroy and initialize spawn attributes object 29095 (REALTIME) 29096 SYNOPSIS 29097 SPN #include 29098 int posix_spawnattr_destroy(posix_spawnattr_t *attr); 29099 int posix_spawnattr_init(posix_spawnattr_t *attr); 29100 29101 DESCRIPTION 29102 A spawn attributes object is of type posix_spawnattr_t (defined in ) and is used to 29103 specify the inheritance of process attributes across a spawn operation. IEEE Std. 1003.1-200x 29104 does not define comparison or assignment operators for the type posix_spawnattr_t. 29105 The posix_spawnattr_destroy( ) function destroys a spawn attributes object. The effect of 29106 subsequent use of the object is undefined until the object is reinitialized by another call to 29107 posix_spawnattr_init( ). An implementation may cause posix_spawnattr_destroy( ) to set the object 29108 referenced by attr to an invalid value. 29109 The posix_spawnattr_init( ) function initializes a spawn attributes object attr with the default 29110 value for all of the individual attributes used by the implementation. The effect of initializing an | 29111 already initialized spawn attributes option is undefined. | 29112 Each implementation shall document the individual attributes it uses and their default values 29113 unless these values are defined by IEEE Std. 1003.1-200x. Attributes not defined by 29114 IEEE Std. 1003.1-200x, their default values, and the names of the associated functions to get and 29115 set those attribute values are implementation-defined. | 29116 The resulting spawn attributes object (possibly modified by setting individual attribute values), 29117 is used to modify the behavior of posix_spawn( ) or posix_spawnp( ). After a spawn attributes 29118 object has been used to spawn a process by a call to a posix_spawn( ) or posix_spawnp( ), any 29119 function affecting the attributes object (including destruction) does not affect any process that 29120 has been spawned in this way. | 29121 RETURN VALUE 29122 Upon successful completion, posix_spawnattr_destroy( ) and posix_spawnattr_init( ) shall return 29123 zero; otherwise, an error number shall be returned to indicate the error. 29124 ERRORS 29125 The posix_spawnattr_init( ) function shall fail if: 29126 [ENOMEM] Insufficient memory exists to initialize the spawn attributes object. 29127 The posix_spawnattr_destroy( ) function may fail if: 29128 [EINVAL] The value specified by attr is invalid. 29129 EXAMPLES 29130 None. 29131 APPLICATION USAGE 29132 These functions are part of the Spawn option and need not be provided on all implementations. | 29133 RATIONALE 29134 The original spawn interface proposed in IEEE Std. 1003.1-200x defined the attributes that 29135 specify the inheritance of process attributes across a spawn operation as a structure. In order to 29136 be able to separate optional individual attributes under their appropriate options (that is, the 29137 spawn-schedparam and spawn-schedpolicy attributes depending upon the Process Scheduling System Interfaces, Issue 6 1405 posix_spawnattr_destroy( ) System Interfaces 29138 option), and also for extensibility and consistency with the newer POSIX interfaces, the 29139 attributes interface has been changed to an opaque data type. This interface now consists of the 29140 type posix_spawnattr_t, representing a spawn attributes object, together with associated 29141 functions to initialize or destroy the attributes object, and to set or get each individual attribute. 29142 Although the new object-oriented interface is more verbose than the original structure, it is 29143 simple to use, more extensible, and easy to implement. 29144 FUTURE DIRECTIONS 29145 None. 29146 SEE ALSO 29147 posix_spawn( ), posix_spawnattr_getsigdefault( ), posix_spawnattr_getflags( ), | 29148 posix_spawnattr_getpgroup( ), posix_spawnattr_getschedparam( ), posix_spawnattr_getschedpolicy( ), 29149 posix_spawnattr_getsigmask( ), posix_spawnattr_setsigdefault( ), posix_spawnattr_setflags( ), | 29150 posix_spawnattr_setpgroup( ), posix_spawnattr_setsigmask( ), posix_spawnattr_setschedpolicy( ), 29151 posix_spawnattr_setschedparam( ), posix_spawnp( ), the Base Definitions volume of | 29152 IEEE Std. 1003.1-200x, | 29153 CHANGE HISTORY 29154 First released in Issue 6. Derived from IEEE Std. 1003.1d-1999. | 29155 IEEE PASC Interpretation 1003.1 #106 is included, noting that the effect of initializing an already | 29156 initialized spawn attributes option is undefined. | 1406 Technical Standard (2000) (Draft July 31, 2000) System Interfaces posix_spawnattr_getflags( ) 29157 NAME 29158 posix_spawnattr_getflags, posix_spawnattr_setflags - get and set spawn-flags attribute of 29159 spawn attributes object (REALTIME) 29160 SYNOPSIS 29161 SPN #include 29162 int posix_spawnattr_getflags(const posix_spawnattr_t *restrict attr, | 29163 short *restrict flags); | 29164 int posix_spawnattr_setflags(posix_spawnattr_t *attr, short flags); | 29165 29166 DESCRIPTION 29167 The spawn-flags attribute is used to indicate which process attributes are to be changed in the 29168 new process image when invoking posix_spawn( ) or posix_spawnp( ). It is the bitwise-inclusive 29169 OR of zero or more of the flags POSIX_SPAWN_RESETIDS, POSIX_SPAWN_SETPGROUP, | 29170 PS POSIX_SPAWN_SETSIGDEF, and POSIX_SPAWN_SETSIGMASK, | 29171 POSIX_SPAWN_SETSCHEDPARAM, and POSIX_SPAWN_SETSCHEDULER. In addition, if the | 29172 Process Scheduling option is supported, the flags POSIX_SPAWN_SETSCHEDPARAM and 29173 POSIX_SPAWN_SETSCHEDULER shall also be supported. These flags are defined in 29174 . The default value of this attribute shall be with no flags set. 29175 The posix_spawnattr_getflags( ) function obtains the value of the spawn-flags attribute from the 29176 attributes object referenced by attr. 29177 The posix_spawnattr_setflags( ) function is used to set the spawn-flags attribute in an initialized 29178 attributes object referenced by attr. 29179 RETURN VALUE 29180 Upon successful completion, posix_spawnattr_getflags( ) shall return zero and store the value of 29181 the spawn-flags attribute of attr into the object referenced by the flags parameter; otherwise, an 29182 error number shall be returned to indicate the error. 29183 Upon successful completion, posix_spawnattr_setflags( ) shall return zero; otherwise, an error 29184 number shall be returned to indicate the error. 29185 ERRORS 29186 These functions may fail if: 29187 [EINVAL] The value specified by attr is invalid. 29188 The posix_spawnattr_setflags( ) function may fail if: 29189 [EINVAL] The value of the attribute being set is not valid. 29190 EXAMPLES 29191 None. 29192 APPLICATION USAGE 29193 These functions are part of the Spawn option and need not be provided on all implementations. | 29194 RATIONALE 29195 None. 29196 FUTURE DIRECTIONS 29197 None. System Interfaces, Issue 6 1407 posix_spawnattr_getflags( ) System Interfaces 29198 SEE ALSO 29199 posix_spawn( ), ,=1 .ds ;p posix_spawnattr_destroy( ) (on page 1405), ,=1 .ds ;p 29200 posix_spawnattr_init( ) (on page 1419), posix_spawnattr_getsigdefault( ), | 29201 posix_spawnattr_getpgroup( ), posix_spawnattr_getschedparam( ), posix_spawnattr_getschedpolicy( ), 29202 posix_spawnattr_getsigmask( ), posix_spawnattr_setsigdefault( ), posix_spawnattr_setpgroup( ), | 29203 posix_spawnattr_setschedparam( ), posix_spawnattr_setschedpolicy( ), posix_spawnattr_setsigmask( ), 29204 posix_spawnp( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | 29205 CHANGE HISTORY 29206 First released in Issue 6. Derived from IEEE Std. 1003.1d-1999. 1408 Technical Standard (2000) (Draft July 31, 2000) System Interfaces posix_spawnattr_getpgroup( ) 29207 NAME 29208 posix_spawnattr_getpgroup, posix_spawnattr_setpgroup - get and set spawn-pgroup attribute 29209 of spawn attributes object (REALTIME) 29210 SYNOPSIS 29211 SPN #include 29212 int posix_spawnattr_getpgroup(const posix_spawnattr_t *restrict attr, | 29213 pid_t *restrict pgroup); | 29214 int posix_spawnattr_setpgroup(posix_spawnattr_t *attr, pid_t pgroup); | 29215 29216 DESCRIPTION 29217 The spawn-pgroup attribute represents the process group to be joined by the new process image 29218 in a spawn operation (if POSIX_SPAWN_SETPGROUP is set in the spawn-flags attribute). The 29219 default value of this attribute shall be zero. 29220 The posix_spawnattr_getpgroup( ) function obtains the value of the spawn-pgroup attribute from 29221 the attributes object referenced by attr. 29222 The posix_spawnattr_setpgroup( ) function is used to set the spawn-pgroup attribute in an 29223 initialized attributes object referenced by attr. 29224 RETURN VALUE 29225 Upon successful completion, posix_spawnattr_getpgroup( ) shall return zero and store the value of 29226 the spawn-pgroup attribute of attr into the object referenced by the pgroup parameter; otherwise, 29227 an error number shall be returned to indicate the error. 29228 Upon successful completion, posix_spawnattr_setpgroup( ) shall return zero; otherwise, an error 29229 number shall be returned to indicate the error. 29230 ERRORS 29231 These functions may fail if: 29232 [EINVAL] The value specified by attr is invalid. 29233 The posix_spawnattr_setpgroup( ) function may fail if: 29234 [EINVAL] The value of the attribute being set is not valid. 29235 EXAMPLES 29236 None. 29237 APPLICATION USAGE 29238 These functions are part of the Spawn option and need not be provided on all implementations. | 29239 RATIONALE 29240 None. 29241 FUTURE DIRECTIONS 29242 None. 29243 SEE ALSO 29244 posix_spawn( ), posix_spawnattr_destroy( ), posix_spawnattr_init( ), posix_spawnattr_getsigdefault( ), | 29245 posix_spawnattr_getflags( ), posix_spawnattr_getschedparam( ), posix_spawnattr_getschedpolicy( ), 29246 posix_spawnattr_getsigmask( ), posix_spawnattr_setsigdefault( ), posix_spawnattr_setflags( ), | 29247 posix_spawnattr_setschedparam( ), posix_spawnattr_setschedpolicy( ), posix_spawnattr_setsigmask( ), 29248 posix_spawnp( ), the Base Definitions volume of IEEE Std. 1003.1-200x, | System Interfaces, Issue 6 1409 posix_spawnattr_getpgroup( ) System Interfaces 29249 CHANGE HISTORY 29250 First released in Issue 6. Derived from IEEE Std. 1003.1d-1999. | 1410 Technical Standard (2000) (Draft July 31, 2000) System Interfaces posix_spawnattr_getschedparam( ) 29251 NAME 29252 posix_spawnattr_getschedparam, posix_spawnattr_setschedparam - get and set spawn- 29253 schedparam attribute of spawn attributes object (REALTIME) 29254 SYNOPSIS 29255 SPN PS #include | 29256 #include | 29257 int posix_spawnattr_getschedparam(const posix_spawnattr_t *restrict attr,| 29258 struct sched_param *restrict schedparam); | 29259 int posix_spawnattr_setschedparam(posix_spawnattr_t *restrict attr, | 29260 const struct sched_param *restrict schedparam); | 29261 | 29262 DESCRIPTION 29263 The spawn-schedparam attribute represents the scheduling parameters to be assigned to the new 29264 process image in a spawn operation (if POSIX_SPAWN_SETSCHEDULER or 29265 POSIX_SPAWN_SETSCHEDPARAM is set in the spawn-flags attribute). The default value of this 29266 attribute is unspecified. 29267 The posix_spawnattr_getschedparam( ) function obtains the value of the spawn-schedparam attribute 29268 from the attributes object referenced by attr. 29269 The posix_spawnattr_setschedparam( ) function is used to set the spawn-schedparam attribute in an 29270 initialized attributes object referenced by attr. 29271 RETURN VALUE 29272 Upon successful completion, posix_spawnattr_getschedparam( ) shall return zero and store the 29273 value of the spawn-schedparam attribute of attr into the object referenced by the schedparam 29274 parameter; otherwise, an error number shall be returned to indicate the error. 29275 Upon successful completion, posix_spawnattr_setschedparam( ) shall return zero; otherwise, an 29276 error number shall be returned to indicate the error. 29277 ERRORS 29278 These functions may fail if: 29279 [EINVAL] The value specified by attr is invalid. 29280 The posix_spawnattr_setschedparam( ) function may fail if: 29281 [EINVAL] The value of the attribute being set is not valid. 29282 EXAMPLES 29283 None. 29284 APPLICATION USAGE 29285 These functions are part of the Spawn and Process Scheduling options and need not be provided | 29286 on all implementations. | 29287 RATIONALE 29288 None. 29289 FUTURE DIRECTIONS 29290 None. 29291 SEE ALSO 29292 posix_spawn( ), posix_spawnattr_destroy( ), posix_spawnattr_init( ), posix_spawnattr_getsigdefault( ), | 29293 posix_spawnattr_getflags( ), posix_spawnattr_getpgroup( ), posix_spawnattr_getschedpolicy( ), 29294 posix_spawnattr_getsigmask( ), posix_spawnattr_setsigdefault( ), posix_spawnattr_setflags( ), | System Interfaces, Issue 6 1411 posix_spawnattr_getschedparam( ) System Interfaces 29295 posix_spawnattr_setpgroup( ), posix_spawnattr_setschedpolicy( ), posix_spawnattr_setsigmask( ), 29296 posix_spawnp( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , | 29297 CHANGE HISTORY 29298 First released in Issue 6. Derived from IEEE Std. 1003.1d-1999. 1412 Technical Standard (2000) (Draft July 31, 2000) System Interfaces posix_spawnattr_getschedpolicy( ) 29299 NAME 29300 posix_spawnattr_getschedpolicy, posix_spawnattr_setschedpolicy - get and set spawn- 29301 schedpolicy attribute of spawn attributes object (REALTIME) 29302 SYNOPSIS 29303 SPN PS #include | 29304 #include | 29305 int posix_spawnattr_getschedpolicy(const posix_spawnattr_t *restrict attr,| 29306 int *restrict schedpolicy); | 29307 int posix_spawnattr_setschedpolicy(posix_spawnattr_t *attr, | 29308 int schedpolicy); 29309 29310 DESCRIPTION 29311 The spawn-schedpolicy attribute represents the scheduling policy to be assigned to the new 29312 process image in a spawn operation (if POSIX_SPAWN_SETSCHEDULER is set in the spawn- 29313 flags attribute). The default value of this attribute is unspecified. 29314 The posix_spawnattr_getschedpolicy( ) function obtains the value of the spawn-schedpolicy attribute 29315 from the attributes object referenced by attr. 29316 The posix_spawnattr_setschedpolicy( ) function is used to set the spawn-schedpolicy attribute in an 29317 initialized attributes object referenced by attr. 29318 RETURN VALUE 29319 Upon successful completion, posix_spawnattr_getschedpolicy( ) shall return zero and store the 29320 value of the spawn-schedpolicy attribute of attr into the object referenced by the schedpolicy 29321 parameter; otherwise, an error number shall be returned to indicate the error. 29322 Upon successful completion, posix_spawnattr_setschedpolicy( ) shall return zero; otherwise, an 29323 error number shall be returned to indicate the error. 29324 ERRORS 29325 These functions may fail if: 29326 [EINVAL] The value specified by attr is invalid. 29327 The posix_spawnattr_setschedpolicy( ) function may fail if: 29328 [EINVAL] The value of the attribute being set is not valid. 29329 EXAMPLES 29330 None. 29331 APPLICATION USAGE 29332 These functions are part of the Spawn and Process Scheduling options and need not be provided | 29333 on all implementations. | 29334 RATIONALE 29335 None. 29336 FUTURE DIRECTIONS 29337 None. 29338 SEE ALSO 29339 posix_spawn( ), posix_spawnattr_destroy( ), posix_spawnattr_init( ), posix_spawnattr_getsigdefault( ), | 29340 posix_spawnattr_getflags( ), posix_spawnattr_getpgroup( ), posix_spawnattr_getschedparam( ), 29341 posix_spawnattr_getsigmask( ), posix_spawnattr_setsigdefault( ), posix_spawnattr_setflags( ), | 29342 posix_spawnattr_setpgroup( ), posix_spawnattr_setschedparam( ), posix_spawnattr_setsigmask( ), System Interfaces, Issue 6 1413 posix_spawnattr_getschedpolicy( ) System Interfaces 29343 posix_spawnp( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , | 29344 CHANGE HISTORY | 29345 First released in Issue 6. Derived from IEEE Std. 1003.1d-1999. 1414 Technical Standard (2000) (Draft July 31, 2000) System Interfaces posix_spawnattr_getsigdefault( ) 29346 NAME | 29347 posix_spawnattr_getsigdefault, posix_spawnattr_setsigdefault - get and set spawn-sigdefault | 29348 attribute of spawn attributes object (REALTIME) | 29349 SYNOPSIS | 29350 SPN #include | 29351 #include | 29352 int posix_spawnattr_getsigdefault(const posix_spawnattr_t *restrict attr,| 29353 sigset_t *restrict sigdefault); | 29354 int posix_spawnattr_setsigdefault(posix_spawnattr_t *restrict attr, | 29355 const sigset_t *restrict sigdefault); | 29356 | 29357 DESCRIPTION | 29358 The spawn-sigdefault attribute represents the set of signals to be forced to default signal handling | 29359 in the new process image (if POSIX_SPAWN_SETSIGDEF is set in the spawn-flags attribute) by a | 29360 spawn operation. The default value of this attribute shall be an empty signal set. | 29361 The posix_spawnattr_getsigdefault( ) function obtains the value of the spawn-sigdefault attribute | 29362 from the attributes object referenced by attr. | 29363 The posix_spawnattr_setsigdefault( ) function is used to set the spawn-sigdefault attribute in an | 29364 initialized attributes object referenced by attr. | 29365 RETURN VALUE | 29366 Upon successful completion, posix_spawnattr_getsigdefault( ) shall return zero and store the value | 29367 of the spawn-sigdefault attribute of attr into the object referenced by the sigdefault parameter; | 29368 otherwise, an error number shall be returned to indicate the error. | 29369 Upon successful completion, posix_spawnattr_setsigdefault( ) shall return zero; otherwise, an error | 29370 number shall be returned to indicate the error. | 29371 ERRORS | 29372 These functions may fail if: | 29373 [EINVAL] The value specified by attr is invalid. | 29374 The posix_spawnattr_setsigdefault( ) function may fail if: | 29375 [EINVAL] The value of the attribute being set is not valid. | 29376 EXAMPLES | 29377 None. | 29378 APPLICATION USAGE | 29379 These functions are part of the Spawn option and need not be provided on all implementations. | 29380 RATIONALE | 29381 None. | 29382 FUTURE DIRECTIONS | 29383 None. | 29384 SEE ALSO | 29385 posix_spawn( ), posix_spawnattr_destroy( ), posix_spawnattr_init( ), posix_spawnattr_getflags( ), | 29386 posix_spawnattr_getpgroup( ), posix_spawnattr_getschedparam( ), posix_spawnattr_getschedpolicy( ), | 29387 posix_spawnattr_getsigmask( ), posix_spawnattr_setflags( ), posix_spawnattr_setpgroup( ), | 29388 posix_spawnattr_setschedparam( ), posix_spawnattr_setschedpolicy( ), posix_spawnattr_setsigmask( ), | 29389 posix_spawnp( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , | System Interfaces, Issue 6 1415 posix_spawnattr_getsigdefault( ) System Interfaces 29390 CHANGE HISTORY || 29391 First released in Issue 6. Derived from IEEE Std. 1003.1d-1999. | 1416 Technical Standard (2000) (Draft July 31, 2000) System Interfaces posix_spawnattr_getsigmask( ) 29392 NAME 29393 posix_spawnattr_getsigmask, posix_spawnattr_setsigmask - get and set spawn-sigmask 29394 attribute of spawn attributes object (REALTIME) 29395 SYNOPSIS 29396 SPN #include 29397 #include 29398 int posix_spawnattr_getsigmask(const posix_spawnattr_t *restrict attr, | 29399 sigset_t *restrict sigmask); | 29400 int posix_spawnattr_setsigmask(posix_spawnattr_t *restrict attr, | 29401 const sigset_t *restrict sigmask); | 29402 | 29403 DESCRIPTION 29404 The spawn-sigmask attribute represents the signal mask in effect in the new process image of a 29405 spawn operation (if POSIX_SPAWN_SETSIGMASK is set in the spawn-flags attribute). The 29406 default value of this attribute is unspecified. 29407 The posix_spawnattr_getsigmask( ) function obtains the value of the spawn-sigmask attribute from 29408 the attributes object referenced by attr. 29409 The posix_spawnattr_setsigmask( ) function is used to set the spawn-sigmask attribute in an 29410 initialized attributes object referenced by attr. 29411 RETURN VALUE 29412 Upon successful completion, posix_spawnattr_getsigmask( ) shall return zero and store the value 29413 of the spawn-sigmask attribute of attr into the object referenced by the sigmask parameter; 29414 otherwise, an error number shall be returned to indicate the error. 29415 Upon successful completion, posix_spawnattr_setsigmask( ) shall return zero; otherwise, an error 29416 number shall be returned to indicate the error. 29417 ERRORS 29418 These functions may fail if: 29419 [EINVAL] The value specified by attr is invalid. 29420 The posix_spawnattr_setsigmask( ) function may fail if: 29421 [EINVAL] The value of the attribute being set is not valid. 29422 EXAMPLES 29423 None. 29424 APPLICATION USAGE 29425 These functions are part of the Spawn option and need not be provided on all implementations. | 29426 RATIONALE 29427 None. 29428 FUTURE DIRECTIONS 29429 None. 29430 SEE ALSO 29431 posix_spawn( ), posix_spawnattr_destroy( ), posix_spawnattr_init( ), posix_spawnattr_getsigdefault( ), | 29432 posix_spawnattr_getflags( ), posix_spawnattr_getpgroup( ), posix_spawnattr_getschedparam( ), 29433 posix_spawnattr_getschedpolicy( ), posix_spawnattr_setsigdefault( ), posix_spawnattr_setflags( ), | 29434 posix_spawnattr_setpgroup( ), posix_spawnattr_setschedparam( ), posix_spawnattr_setschedpolicy( ), 29435 posix_spawnp( ), the Base Definitions volume of IEEE Std. 1003.1-200x, , | System Interfaces, Issue 6 1417 posix_spawnattr_getsigmask( ) System Interfaces 29436 CHANGE HISTORY 29437 First released in Issue 6. Derived from IEEE Std. 1003.1d-1999. 1418 Technical Standard (2000) (Draft July 31, 2000) System Interfaces posix_spawnattr_init( ) 29438 NAME 29439 posix_spawnattr_init - initialize spawn attributes object (REALTIME) 29440 SYNOPSIS 29441 SPN #include 29442 int posix_spawnattr_init(posix_spawnattr_t *attr); 29443 29444 DESCRIPTION | 29445 Refer to posix_spawnattr_destroy( ). System Interfaces, Issue 6 1419 posix_spawnattr_setflags( ) System Interfaces 29446 NAME 29447 posix_spawnattr_setflags - set spawn-flags attribute of spawn attributes object (REALTIME) 29448 SYNOPSIS 29449 SPN #include 29450 int posix_spawnattr_setflags(posix_spawnattr_t *attr, short flags); 29451 29452 DESCRIPTION 29453 Refer to posix_spawnattr_getflags( ). 1420 Technical Standard (2000) (Draft July 31, 2000) System Interfaces posix_spawnattr_setpgroup( ) 29454 NAME 29455 posix_spawnattr_setpgroup - set spawn-pgroup attribute of spawn attributes object 29456 (REALTIME) 29457 SYNOPSIS 29458 SPN #include 29459 int posix_spawnattr_setpgroup(posix_spawnattr_t *attr, pid_t pgroup); 29460 29461 DESCRIPTION 29462 Refer to posix_spawnattr_getpgroup( ). System Interfaces, Issue 6 1421 posix_spawnattr_setschedparam( ) System Interfaces 29463 NAME 29464 posix_spawnattr_setschedparam - set spawn-schedparam attribute of spawn attributes object 29465 (REALTIME) 29466 SYNOPSIS 29467 SPN PS #include 29468 #include 29469 int posix_spawnattr_setschedparam(posix_spawnattr_t *restrict attr, | 29470 const struct sched_param *restrict schedparam); | 29471 | 29472 DESCRIPTION 29473 Refer to posix_spawnattr_getschedparam( ). 1422 Technical Standard (2000) (Draft July 31, 2000) System Interfaces posix_spawnattr_setschedpolicy( ) 29474 NAME 29475 posix_spawnattr_setschedpolicy - set spawn-schedpolicy attribute of spawn attributes object 29476 (REALTIME) 29477 SYNOPSIS 29478 SPN PS #include 29479 #include 29480 int posix_spawnattr_setschedpolicy(posix_spawnattr_t *attr, 29481 int schedpolicy); 29482 29483 DESCRIPTION | 29484 Refer to posix_spawnattr_getschedpolicy( ). System Interfaces, Issue 6 1423 posix_spawnattr_setsigdefault( ) System Interfaces 29485 NAME | 29486 posix_spawnattr_setsigdefault - set spawn-sigdefault attribute of spawn attributes object | 29487 (REALTIME) | 29488 SYNOPSIS | 29489 SPN #include | 29490 #include | 29491 int posix_spawnattr_setsigdefault(posix_spawnattr_t *restrict attr, | 29492 const sigset_t *restrict sigdefault); | 29493 | 29494 DESCRIPTION || 29495 Refer to posix_spawnattr_getsigdefault( ). | 1424 Technical Standard (2000) (Draft July 31, 2000) System Interfaces posix_spawnattr_setsigmask( ) 29496 NAME 29497 posix_spawnattr_setsigmask - set spawn-sigmask attribute of spawn attributes object 29498 (REALTIME) 29499 SYNOPSIS 29500 SPN #include 29501 #include 29502 int posix_spawnattr_setsigmask(posix_spawnattr_t *restrict attr, | 29503 const sigset_t *restrict sigmask); | 29504 | 29505 DESCRIPTION 29506 Refer to posix_spawnattr_getsigmask( ). System Interfaces, Issue 6 1425 posix_spawnp( ) System Interfaces 29507 NAME 29508 posix_spawnp - spawn a process (REALTIME) 29509 SYNOPSIS 29510 SPN #include 29511 int posix_spawnp(pid_t *restrict pid, const char *restrict file, | 29512 const posix_spawn_file_actions_t *file_actions, | 29513 const posix_spawnattr_t *restrict attrp, | 29514 char *const argv[restrict], char *const envp[restrict]); | 29515 | 29516 DESCRIPTION | 29517 Refer to posix_spawn( ). 1426 Technical Standard (2000) (Draft July 31, 2000) System Interfaces posix_trace_attr_destroy( ) 29518 NAME | 29519 posix_trace_attr_destroy, posix_trace_attr_init - trace stream attributes object destroy and | 29520 initialization | 29521 SYNOPSIS | 29522 TRC #include | 29523 int posix_trace_attr_destroy(trace_attr_t *attr); | 29524 int posix_trace_attr_init(trace_attr_t *attr); | 29525 | 29526 DESCRIPTION | 29527 The posix_trace_attr_destroy( ) function is used to destroy an initialized trace attributes object. | 29528 The results of using the attributes object after it has been destroyed are unspecified. A destroyed | 29529 trace attributes object can be reinitialized using posix_trace_attr_init( ). | 29530 The posix_trace_attr_init( ) function initializes a trace attributes object attr with the default value | 29531 for all of the individual attributes used by a given implementation. The read-only generation- | 29532 version and clock-resolution attributes of the newly initialized trace attributes object shall be set to | 29533 their appropriate values (Section 2.11.1.2 (on page 578)). | 29534 The effect of initializing an already-initialized trace attributes object is unspecified. | 29535 Implementations may add extensions to the trace attributes object structure as permitted in the | 29536 Base Definitions volume of IEEE Std. 1003.1-200x, Chapter 2, Conformance. | 29537 The resulting attributes object (possibly modified by setting individual attributes values), when | 29538 used by posix_trace_create( ), defines the attributes of the trace stream created. A single attributes | 29539 object can be used in multiple calls to posix_trace_create( ). After one or more trace streams have | 29540 been created using an attributes object, any function affecting that attributes object, including | 29541 destruction, does not affect any trace stream previously created. An initialized attributes object | 29542 also serves to receive the attributes of an existing trace stream or trace log when calling the | 29543 posix_trace_get_attr( ) function. | 29544 RETURN VALUE | 29545 Upon successful completion, these functions shall return a value of zero. Otherwise, they shall | 29546 return the corresponding error number. | 29547 ERRORS | 29548 The posix_trace_attr_destroy( ) function may fail if: | 29549 [EINVAL] The value of attr is invalid. | 29550 The posix_trace_attr_init( ) function shall fail if: | 29551 [ENOMEM] Insufficient memory exists to initialize the trace attributes object. | 29552 EXAMPLES | 29553 None. | 29554 APPLICATION USAGE | 29555 None. | 29556 RATIONALE | 29557 None. | 29558 FUTURE DIRECTIONS | 29559 None. | System Interfaces, Issue 6 1427 posix_trace_attr_destroy( ) System Interfaces 29560 SEE ALSO | 29561 posix_trace_create( ), posix_trace_get_attr( ), uname( ), the Base Definitions volume of | 29562 IEEE Std. 1003.1-200x, | 29563 CHANGE HISTORY || 29564 First released in Issue 6. Derived from IEEE Std. 1003.1q-2000. | 1428 Technical Standard (2000) (Draft July 31, 2000) System Interfaces posix_trace_attr_getclockres( ) 29565 NAME | 29566 posix_trace_attr_getclockres, posix_trace_attr_getcreatetime, posix_trace_attr_getgenversion, | 29567 posix_trace_attr_getname, posix_trace_attr_setname - retrieve and set information about a | 29568 trace stream | 29569 SYNOPSIS | 29570 TRC #include | 29571 #include | 29572 int posix_trace_attr_getclockres(const trace_attr_t *attr, | 29573 struct timespec *resolution); | 29574 int posix_trace_attr_getcreatetime(const trace_attr_t *attr, | 29575 struct timespec *createtime); | 29576 #include | 29577 int posix_trace_attr_getgenversion(const trace_attr_t *attr, | 29578 char *genversion); | 29579 int posix_trace_attr_getname(const trace_attr_t *attr, | 29580 char *tracename); | 29581 int posix_trace_attr_setname(trace_attr_t *attr, | 29582 const char *tracename); | 29583 | 29584 DESCRIPTION | 29585 The posix_trace_attr_getclockres( ) function shall copy the clock resolution of the clock used to | 29586 generate timestamps from the clock-resolution attribute of the attributes object pointed to by the | 29587 attr argument into the structure pointed to by the resolution argument. | 29588 The posix_trace_attr_getcreatetime( ) function shall copy the trace stream creation time from the | 29589 creation-time attribute of the attributes object pointed to by the attr argument into the structure | 29590 pointed to by the createtime argument. The creation-time attribute shall represent the time of | 29591 creation of the trace stream. | 29592 The posix_trace_attr_getgenversion( ) function shall copy the string containing version information | 29593 from the generation-version attribute of the attributes object pointed to by the attr argument into | 29594 the string pointed to by the genversion argument. The genversion argument shall be the address of | 29595 a character array which can store at least {TRACE_NAME_MAX} characters. | 29596 The posix_trace_attr_getname( ) function shall copy the string containing the trace name from the | 29597 trace-name attribute of the attributes object pointed to by the attr argument into the string | 29598 pointed to by the tracename argument. The tracename argument shall be the address of a character | 29599 array which can store at least {TRACE_NAME_MAX} characters. | 29600 The posix_trace_attr_setname( ) function shall set the name in the trace-name attribute of the | 29601 attributes object pointed to by the attr argument, using the trace name string supplied by the | 29602 tracename argument. If the supplied string contains more than {TRACE_NAME_MAX} | 29603 characters, the name copied into the trace-name attribute may be truncated to one less than the | 29604 length of {TRACE_NAME_MAX} characters. The default value is a null string. | 29605 RETURN VALUE | 29606 Upon successful completion, these functions shall return a value of zero. Otherwise, they shall | 29607 return the corresponding error number. | 29608 If successful, the posix_trace_attr_getclockres( ) function stores the clock-resolution attribute value | 29609 in the object pointed to by resolution. Otherwise, the content of this object is unspecified. | System Interfaces, Issue 6 1429 posix_trace_attr_getclockres( ) System Interfaces 29610 If successful, the posix_trace_attr_getcreatetime( ) function stores the trace stream creation time in | 29611 the object pointed to by createtime. Otherwise, the content of this object is unspecified. | 29612 If successful, the posix_trace_attr_getgenversion( ) function stores the trace version information in | 29613 the string pointed to by genversion. Otherwise, the content of this string is unspecified. | 29614 If successful, the posix_trace_attr_getname( ) function stores the trace name in the string pointed | 29615 to by tracename. Otherwise, the content of this string is unspecified. | 29616 ERRORS | 29617 The posix_trace_attr_getclockres( ), posix_trace_attr_getcreatetime( ), posix_trace_attr_getgenversion( ), | 29618 and posix_trace_attr_getname( ) functions may fail if: | 29619 [EINVAL] The value specified by one of the arguments is invalid. | 29620 EXAMPLES | 29621 None. | 29622 APPLICATION USAGE | 29623 None. | 29624 RATIONALE | 29625 None. | 29626 FUTURE DIRECTIONS | 29627 None. | 29628 SEE ALSO | 29629 posix_trace_attr_init( ), posix_trace_create( ), posix_trace_get_attr( ), uname( ), the Base Definitions | 29630 volume of IEEE Std. 1003.1-200x, , | 29631 CHANGE HISTORY || 29632 First released in Issue 6. Derived from IEEE Std. 1003.1q-2000. | 1430 Technical Standard (2000) (Draft July 31, 2000) System Interfaces posix_trace_attr_getinherited( ) 29633 NAME | 29634 posix_trace_attr_getinherited, posix_trace_attr_getlogfullpolicy, | 29635 posix_trace_attr_getstreamfullpolicy, posix_trace_attr_setinherited, | 29636 posix_trace_attr_setlogfullpolicy, posix_trace_attr_setstreamfullpolicy - retrieve and set the | 29637 behavior of a trace stream | 29638 SYNOPSIS | 29639 TRC #include | 29640 TRC TRI int posix_trace_attr_getinherited(const trace_attr_t *attr, | 29641 int *inheritancepolicy); | 29642 TRC TRL int posix_trace_attr_getlogfullpolicy(const trace_attr_t *attr, | 29643 int *logpolicy); | 29644 TRC int posix_trace_attr_getstreamfullpolicy(const trace_attr_t *attr, | 29645 int *streampolicy); | 29646 TRC TRI int posix_trace_attr_setinherited(trace_attr_t *attr, | 29647 int inheritancepolicy); | 29648 TRC TRL int posix_trace_attr_setlogfullpolicy(trace_attr_t *attr, | 29649 int logpolicy); | 29650 TRC int posix_trace_attr_setstreamfullpolicy(trace_attr_t *attr, | 29651 int streampolicy); | 29652 | 29653 DESCRIPTION | 29654 TRI The posix_trace_attr_getinherited( ) and posix_trace_attr_setinherited( ) functions, respectively, get | 29655 and set the inheritance policy stored in the inheritance attribute for traced processes across the | 29656 fork( ) and spawn( ) operations. The inheritance attribute of the attributes object pointed to by the | 29657 attr argument shall be set to one of the following values defined by manifest constants in the | 29658 header: | 29659 POSIX_TRACE_CLOSE_FOR_CHILD | 29660 After a fork( ) or spawn( ) operation, the child shall not be traced, and tracing of the parent | 29661 shall continue. | 29662 POSIX_TRACE_INHERITED | 29663 After a fork( ) or spawn( ) operation, if the parent is being traced, its child shall be | 29664 concurrently traced using the same trace stream. | 29665 The default value for the inheritance attribute is POSIX_TRACE_CLOSE_FOR_CHILD. | 29666 TRL The posix_trace_attr_getlogfullpolicy( ) and posix_trace_attr_setlogfullpolicy( ) functions, | 29667 respectively, get and set the trace log full policy stored in the log-full-policy attribute of the | 29668 attributes object pointed to by the attr argument. | 29669 The log-full-policy attribute shall be set to one of the following values defined by manifest | 29670 constants in the header: | 29671 POSIX_TRACE_LOOP | 29672 The trace log shall loop until the associated trace stream is stopped. This policy means that | 29673 when the trace log gets full, the file system shall reuse the resources allocated to the oldest | 29674 trace events that were recorded. In this way, the trace log will always contain the most | 29675 recent trace events flushed. | 29676 POSIX_TRACE_UNTIL_FULL | 29677 The trace stream shall be flushed to the trace log until the trace log is full. This condition can | 29678 be deduced from the posix_log_full_status member status (see the posix_trace_status_info( ) | 29679 function). The last recorded trace event shall be the POSIX_TRACE_STOP trace event. | System Interfaces, Issue 6 1431 posix_trace_attr_getinherited( ) System Interfaces 29680 POSIX_TRACE_APPEND | 29681 The associated trace stream shall be flushed to the trace log without log size limitation. If | 29682 the application specifies POSIX_TRACE_APPEND, the implementation shall ignore the | 29683 log-max-size attribute. | 29684 The default value for the log-full-policy attribute is POSIX_TRACE_LOOP. | 29685 The posix_trace_attr_getstreamfullpolicy( ) and posix_trace_attr_setstreamfullpolicy( ) functions, | 29686 respectively, get and set the trace stream full policy stored in the stream-full-policy attribute of the | 29687 attributes object pointed to by the attr argument. | 29688 The stream-full-policy attribute shall be set to one of the following values defined by manifest | 29689 constants in the header: | 29690 POSIX_TRACE_LOOP | 29691 The trace stream shall loop until explicitly stopped by the posix_trace_stop( ) function. This | 29692 policy means that when the trace stream is full, the trace system shall reuse the resources | 29693 allocated to the oldest trace events recorded. In this way, the trace stream will always | 29694 contain the most recent trace events recorded. | 29695 POSIX_TRACE_UNTIL_FULL | 29696 The trace stream will run until the trace stream resources are exhausted. Then the trace | 29697 stream will stop. This condition can be deduced from posix_stream_status and | 29698 posix_stream_full_status statuses (see the posix_trace_status_info( ) function). When this trace | 29699 stream is read, a POSIX_TRACE_STOP trace event shall be reported after reporting the last | 29700 recorded trace event. The trace system shall reuse the resources allocated to any trace | 29701 events already reported-see the posix_trace_getnext_event( ), posix_trace_trygetnext_event( ), | 29702 and posix_trace_timedgetnext_event( ) functions-or already flushed for an active trace stream | 29703 with log if the Trace Log option is supported; see the posix_trace_flush( ) function. The trace | 29704 system shall restart the trace stream when it is empty and may restart it sooner. A | 29705 POSIX_TRACE_START trace event shall be reported before reporting the next recorded | 29706 trace event. | 29707 POSIX_TRACE_FLUSH | 29708 If the Trace Log option is supported, this policy is identical to the | 29709 POSIX_TRACE_UNTIL_FULL trace stream full policy except that the trace stream shall be | 29710 flushed regularly as if posix_trace_flush( ) had been explicitly called. Defining this policy for | 29711 an active trace stream without log shall be invalid.

P LATIN CAPITAL LETTER P 3752 Q LATIN CAPITAL LETTER Q 3753 R LATIN CAPITAL LETTER R 3754 S LATIN CAPITAL LETTER S 3755 T LATIN CAPITAL LETTER T 3756 U LATIN CAPITAL LETTER U 3757 V LATIN CAPITAL LETTER V 3758 W LATIN CAPITAL LETTER W 3759 X LATIN CAPITAL LETTER X 3760 Y LATIN CAPITAL LETTER Y 3761 Z LATIN CAPITAL LETTER Z 3762 [ LEFT SQUARE BRACKET 3763 \ REVERSE SOLIDUS 3764 \ REVERSE SOLIDUS 3765 ] RIGHT SQUARE BRACKET 3766 ^ CIRCUMFLEX ACCENT 3767 ^ CIRCUMFLEX ACCENT 3768 _ LOW LINE 3769 _ _ LOW LINE ____________________________________________________________________________ 134 Technical Standard (2000) (Draft July 28, 2000) Character Set Portable Character Set 3770 _____________________________________________________________________________ 3771 _ Symbolic Name Glyph UCS Description ____________________________________________________________________________ 3772 ` GRAVE ACCENT 3773 a LATIN SMALL LETTER A 3774 b LATIN SMALL LETTER B 3775 c LATIN SMALL LETTER C 3776 d LATIN SMALL LETTER D 3777 e LATIN SMALL LETTER E 3778 f LATIN SMALL LETTER F 3779 g LATIN SMALL LETTER G 3780 h LATIN SMALL LETTER H 3781 i LATIN SMALL LETTER I 3782 j LATIN SMALL LETTER J 3783 k LATIN SMALL LETTER K 3784 l LATIN SMALL LETTER L 3785 m LATIN SMALL LETTER M 3786 n LATIN SMALL LETTER N 3787 o LATIN SMALL LETTER O 3788